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PREFACE 



Record Management Services for the PDP-11 (RMS-11) provides powerful 
data management capabilities. The RMS-11 User's Guide tells you about 
those capabilities and how to use them. This manual is designed as a 
reference for MACRO-11 programmers. 

RMS-11 is a set of software routines that transfers data between a 
running program, which uses data in a logical form called records, and 
the file processor portion of an operating system, which maintains the 
physical structure of the data on a storage device. 

NOTE 

You can use RMS-11 Indexed files only if you have purchased 
the RMS-11K software product. Your system manager can tell 
you if your system includes this capability. 



PREREQUISITES 

To read this manual, you should be a MACRO-11 programmer who has read 
and understood the RMS-11 User's Guide. 



STRUCTURE OF THE MANUAL 

Chapter 1 tells you how to use RMS-11 routines in a MACRO-11 pro- 
gram, including the minimum requirements and the order in 
which you must use them. 

Chapter 2 covers the means of providing buffer space for RMS-11 op- 
erations. 

Chapter 3 describes the fields of the File Access Block. 

Chapter 4 describes the fields of the Record Access Block. 

Chapter 5 describes the fields of the different types of Extended 
Attribute Blocks. 

Chapter 6 describes the fields of the Name Block. 

Chapter 7 describes the field access macros. 

Chapter 8 describes the file and record operation macros. 

Chapter 9 describes the use of Block I/O. 
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Appendixes provide supplementary information, such as: 

RMS-11 success and error completion codes 

Sample RMS-11 programs 

Routine to convert 64-bit date-time information to 

ASCII 



ASSOCIATED DOCUMENTS 

The RMS-11 documentation set contains the following manuals: 

RMS-11 User's Guide 

RMS-11 MACRO-11 Reference Manual 

RMS-11 Installation Guide 

You must also use operating system documentation. See the Documenta- 
tion Directory for your operating system. 
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DOCUMENTATION CONVENTIONS 



RMS-11 operates similarly on the supporting operating systems (see Ap- 
pendix A of the RMS-11 User's Guide). Therefore, it should be possi- 
ble to produce a single manual describing that operation. However, 
the differences among operating systems present a barrier to that un- 
ification. The following conventions are designed to enable you to 
hurdle that fence. 



DIFFERENCES IN OPERATING SYSTEM FUNCTIONS 

Details that are common to the operating systems are printed in black, 
and the details that are specific to one operating system or another 
are printed in color as follows: 

• RSTS/E-specif ic information is printed in red. 

• IAS-, RSX-11M-, and VAX-specific information is printed in blue. 

SYNTAX DESCRIPTIONS 

In the descriptions of macro usage, this manual includes a general 
form for each macro, using the following conventions: 

REQUIRED You must include all uppercase char- 

acters as shown. 

user-specific You substitute for lowercase characters 

information specific to your usage. 

[may be used] You can, but do not have to include 

characters in brackets. The convention 
...] means the series can continue until 
it exhausts logical possibilities. 

Punctuation You must use punctuation as shown. 

The descriptions of user control block fields that contain numeric va- 
lues include minimum and maximum specifications. These are logical 
values and normally, are not equal to the physical minimum and maximum 
for the field. 

Additionally, a portion of a field, whether byte or word, described as 
"low order" or "least significant" is the portion with the lower ad- 
dress. 



xvii 



CHAPTER 1 
USING RMS-11 IN A MACRO-11 PROGRAM 



Record Management Services for PDP-11 operating systems (RMS-11) is a 
set of routines that enable programs to process files and records 
within files. The RMS-11 User's Guide describes the features of 
RMS-11. All capabilities supported by an operating system are avail- 
able to a MACRO-11 program. 

To obtain RMS-11 services at run time, your program must contain 
RMS-11 processing macros and user control blocks. The processing ma- 
cros are expanded at assembly time. The resulting code is executed at 
run time to perform the specified operation. Each macro represents a 
program request for a file- or record-related service. 

With every request for a service, information is exchanged between 
your program and the RMS-11 routines via user control blocks. These 
blocks are: 

Block Name Function 

File Access Block (FAB) Describes a file and contains 

file-related information. 

Record Access Block (RAB) Describes a Record Access Stre- 
am and the records being ac- 
cessed by that stream. 

Extended Attribute Block (XAB) Contains file attribute infor- 
mation beyond that in the FAB. 

Name Block (NAM) Describes a location in memory 

containing system- related in- 
formation about a file. 

Prior to issuing a request for an RMS-11 service, your program must 
place information detailing the request in the associated control 
block. 

Example A request to open a file must be accompanied by the name or 
ID of the file, information on how the file will be ac- 
cessed, and details on how the file is to be shared. 



Example A program request to read a record from a file must specify 
an access mode and if appropriate, a key value identifying 
the desired record. 

After a request for service has been processed, RMS-11 uses the same 
control block to return information to your program. When a file has 
been successfully opened, RMS-11 provides attribute information such 
as the organization of the file and the format of the records in the 
file. After successfully retrieving a record from a file, RMS-11 pro- 
vides your program with the location in memory of the record and the 
length of the record. 

The amount of information exchanged between RMS-11 and your program 
varies with the nature of the request and the attributes of the file 
being processed. 

To use RMS-11 routines in a MACRO-11 program, you must understand how 
to : 

1. Declare the RMS-11 facilities that your program requires. 

2. Allocate and initialize user control blocks designed to communi- 
cate with RMS-11. 

3. Access fields in user control blocks at run time. 

4. Perform file and record operations. 

5. Assemble your program modules and task build them with the RMS-11 
routines. 



1.1 DECLARING RMS-11 FACILITIES 

Every program that processes RMS-11 files must contain directives and 
special-purpose macros that declare the RMS-11 facilities required at 
assembly and run time. To declare RMS-11 facilities that are used by 
your program, you must do the following: 

1. List RMS-11 macros in .MCALL directives. 

2. Declare the processing environment. 

3. Declare buffer pool requirements and techniques. 

4. Issue a $INIT or $INITIF macro. 



NOTE 

Unless otherwise noted, RMS-11 macros use decimal radix for 
numeric values. 
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1-2 Using RMS-11 in a MACRO-11 Program 



1.1.1 Listing Names of Required Macro Definitions 



All macros used in your program must be listed as arguments in a 
.MCALL directive. Listing the macros in this way allows the actual 
code of each macro to be read in from the RMS-11 source macro library 
(RMSMAC.MLB) during assembly. 

General form: 

.MCALL arg[ ,arg] . . ] 

where arg is a symbolic name of a macro required in the (assembly of 
your program. The macro names can be listed in any order. 



The number of .MCALL directives can be minimized because some macro 
definitions contain .MCALL directives. Table 1-1 contains the minimum 
.MCALL arguments that provide .MCALL directives for all RMS- 
that can be used in a program. 
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Table 1-1: Minimum Set of .MCALL Arguments 



.MCALL Arguments 



ORG$ 

POOL$B 

$INIT or $INITIF 

$GNCAL 

FAB$B 

RAB$B 

XAB$B 

NAM$B 

$FBCAL 
$RBCAL 



Embedded .MCALL Arguments 



None. 

Central buffer pool declaration macros. 

None. 

Run-time field access macros (described in 
Chapter 7) and completion routine macros (des- 
cribed in this chapter) . 

File Access Block allocation and initialization 
macros (described in this chapter) , field offset 
macros (described in Chapter 3), and 
macros (described in Appendix A). 



error code 



Record Access Block allocation and initialization 
macros (described in this chapter) , field offset 
macros (described in Chapter 4), and 
macros (described in Appendix A). 



error code 



Extended Attribute Block allocation and initiali- 
zation macros (described in this chapter) , field 
offset macros (described in Chapter 5), and error 
code macros (described in Appendix A). 

Name Block allocation and initialization (des- 
cribed in this chapter) , field offset macros 
(described in Chapter 6), and error code macros 
(described in Appendix A). 

File operation macros (described in Chapter 9). 
Record operation macros (described in Chapter 9). 
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As shown in Table 1-1, you can ensure that all RMS-11 macros used in a 
program appear as arguments in .MCALL directives by coding the follow- 
ing sequence of .MCALL directives and macro execution in that program: 

.MCALL ORG$,POOL$B,$INIT 

. MCALL $GNCAL, FAB$B , RAB$B , XAB$B , NAM$B 

.MCALL $FBCAL, $RBCAL 

$GNCAL 

$FBCAL 

$RBCAL 

By issuing the $GNCAL, $FBCAL, and $RBCAL macros, you cause the embed- 
ded .MCALL directives to take effect. 

You can omit any macro names from .MCALL directives that do not apply 
to a particular program. 

Example If the program does not use Name or Extended Attribute 
Blocks, do not include the NAM$B or XAB$B macros. 

You may also omit the $RBCAL or $FBCAL macros and list separately each 
file and record operation macros used by your program. 

NOTE 

If you are allocating control blocks in one module, but 
using field offset and/or error code macros in other mo- 
dules, in those modules you must: 

1. include one or more of the following arguments in .MCALL 
directives 

2. execute the specified macros, in the form: 

macnam RMS$L 
except $RMSTAT, which requires no argument when executed 

.MCALL Arguments Embedded Macro Definitions 
FABOF$ FAB field offsets 

RABOF$ RAB field offsets 

XABOF$ XAB field offsets 

NAMOF$ NAM field offsets 

$RMSTAT Error codes 



.■^^Wk 



1-4 Using RMS-11 in a MACRO- 11 Program 



1.1.2 Declaring the Processing Environment 

You must include one or more ORG$ macros within the set of modules 
that you link together with the Task Builder to produce an executable 
task. All ORG$ macros must be in modules that are part of the root of 
your task. An ORG$ macro for a particular file organization must be 
present even if no record operations are performed when such a file is 
opened . 

The use of ORG$ macros in your source modules enables the Task Builder 
to select for linking only those portions of RMS-11 required by your 
program*. Each ORG$ macro declares a unique combination of file or- 
ganization and record operations. 

General form: 

ORG$ org[ ,<recop[ ,recop. . . ]>] 

where org is the type of file organization as one of the following 
symbolic values: 

IDX = Indexed file organization 
REL = Relative file organization 
SEQ = Sequential file organization 

recop is a symbolic value identifying a type of record operation 
that will be performed on a file of the specified organiza- 
tion. If a single value is included, the angle brackets are 
not needed. If multiple values are specified, you must en- 
close them in angle brackets and use commas to separate each 
value from the preceding value. 

One or more of -the following symbolic values may be speci- 
fied in any order: 

CRE = file of specified organization may be created 

DEL = delete operation 

FIN = find operation 

GET = get operation 

PUT = put operation 

UPD = update operation 

Example The following code declares that one or more Sequential 
files will be created and put operation performed by the 
program. Additionally, one or more Indexed files will be 
opened and find, get, and update operations will be per- 
formed on those files. Finally, one or more Relative files 
will be opened, but no record operations will be performed: 
file operations may be performed. 



ORG$ SEQ,<CRE,PUT> 

ORG$ IDX,<GET,UPD,FIN> 

ni3C<; rrt. 



ORG$ REL 



*When you task build RMS-11 nonoverlaid. If you use an RMS-11 overlay 

structure, the ODL file specifies which RMS-11 modules are linked to 

your program. However, the ORG$ macro still determines which of 
those routines your program can use. 
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1.1.3 Declaring Buffer Pool Requirements 

RMS-11 requires a collection of I/O buffers and internal control 
structures to support file processing at run time. The area in your 
program occupied by these buffers and control structures is known as 
the buffer pool. 

The major portion of the buffer pool is composed of I/O buffers. To 
your program, record processing under RMS-11 appears as the movement 
of records directly between a file and the program itself. However, 
RMS-11 actually uses I/O buffers as intermediate storage during data 
transfers: 

• When your program finds or gets a record, RMS-11 moves the block or 
bucket containing the record from the file to an I/O buffer. Then, 
on a get, RMS-11 moves the record from the buffer to your program. 

• When your program puts, updates, or deletes a record, RMS-11 moves 
the specified data from your program to the I/O buffer. Then, for 
Relative and Indexed files, normally RMS-11 moves the bucket in the 
buffer out to the file immediately. However, for Sequential files 
and for Relative and Indexed files with Deferred Write specified, 
RMS-11 doesn't write out the buffer until it has to be used for 
another operation. 

The size of I/O buffers depends on the organizations of the files 
being processed, the number of files open simultaneously, and the 
number of simultaneously active Record Access Streams. In providing 
the information needed to calculate the size requirements for the I/O 
buffers portion of the buffer pool, you have three choices: 

1. A centralized buffer pool controlled by RMS-11. 

2. Private I/O buffers for one or more files plus a centralized pool 
controlled by RMS-11 for other requirements. 

3. A centralized buffer pool controlled by a routine you provide. 

When RMS-11 controls a centralized buffer pool, RMS-11 allocates I/O 
buffers as well as the internal control structures required for file 
processing from a single area in your program. Normally, this space 
is inaccessible to your program: RMS-11 totally manages the space 
within the pool and allocates portions, as needed, for buffer space 
and control structures for open files. 

You can also allocate private I/O buffers on a per-file basis by spec- 
ifying the address and total size of each buffer in fields of the File 
Access Block associated with a file. When the file is open, this 
buffer space is completely managed by RMS-11 and your program must not 
access it. However, when the file is closed, the private I/O buffer 
space is available for use by your program. 

The major advantage of private I/O buffers is avoidance of fragmenta- 
tion in a centralized buffer pool. Since particular files have vary- 
ing I/O buffer requirements based on their organization, a centralized 
buffer pool can reach the point where there is sufficient total space 
available for the opening of an additional file, but the space is not 
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The presence in your source modules of the macros listed 
allows RMS-11 to determine the size requirements for your program's 
buffer pool. The macros are described in Chapter 2. If you want pri- 
vate I/O buffers for one or more files, you can allocate these on a 
file-by-file basis, either statically (at assembly time) or dynamical- 
ly (at run time) . Refer to the descriptions of the BPA (buffer pool 
address) and BPS (buffer pool size) fields in Chapter 3. 

Finally, you can assume total control over buffer space, allocating it 
when RMS-11 requires it, taking it back when RMS-11 no longer needs 



it. This facility, called Get Space Address (GSA) , is 



should not be used by most programmers, 
requirements for the GSA routine. 
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Table 1-2 


: Space Pool Declaration Macros 




Macro 


Description 


Required 


POOL$B 


Beginning of space pool declaration 


Yes 


P$BDB 


Number of Buffer Descriptor Blocks 


Yes 


P$FAB 


Number of files open simultaneously 


Yes 


P$RAB 


Nonindexed streams connected 
simultaneously 


If Sequential or 
Relative files 


P$RABX 


Indexed streams connected 
simultaneously 


If Indexed files 


P$IDX 


Number of defined keys 


If Indexed files 


P$BUF 


Input/output buffer requirements 


If no BPA or GSA 


POOL$E 


End of space pool declaration 


Yes 
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1.1.4 Initializing the Processing Environment 

Your program must initialize the RMS-11 processing environment at run 
time before the program attempts an RMS-11 operation. You accomplish 
this with the $INIT or $INITIF macro. 

General form: 

$INIT or $INITIF 

The code generated by the $INIT macro unconditionally initializes 
RMS-11 internal control structures at run time. The $INITIF code, 
however, initializes the internal structures only if they have not 
been initialized during the current execution of the task. You use 
the $INITIF macro in program modules that can be the first to use 
RMS-11, but are not always run first. 

RMS-11 clears the Processor Status Word 0-Bit to indicate that ini- 
tialization was successful. Therefore, normally after $INIT, the 
0-Bit is cleared; if the 0-Bit is set, an RMS-11 file was open when 
the macro was initiated and no initialization occurred. Normally 
after $INITIF, the 0-Bit is set; if the 0-Bit is cleared, the pro- 
cessing environment was previously initialized. 

If your program initiates any RMS-11 file or record operation before 
the environment is initialized, RMS-11 returns ER$INI error code. 
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1.2 USER CONTROL BLOCKS 

User control blocks are formatted buffers in your program's address 
space. Each control block consists of data fields that are used to 
exchange information between your program and the RMS-11 routines. 

You must allocate space for control blocks in your program at assembly 
time. You can also establish initial values for many of the data 
fields in these blocks at assembly time; or you can defer setting the 
contents of control block fields until run time. RMS-11 provides spe- 
cial macros that perform the functions needed to support control block 
allocation, assembly-time field initialization, and run-time field ac- 
cess. 



1.2.1 File Access Block (FAB) 

A File Access Block, abbreviated FAB, represents a file during the ex- 
ecution of file operation macros: 

$CLOSE 

$CREATE 

$DISPLAY 

$ERASE 

$EXTEND 

$OPEN 

FAB fields (listed in Table 1-3) must contain the proper values before 
the macro is initiated, but they may be changed after the operation is 
complete because RMS-11 has transferred the pertinent information 
about the file to an internal (nonvisible) structure called an Inter- 
nal File Access Block (IFAB) . 

Therefore, one FAB may be used to represent any number of files as 
long as the FAB is changed appropriately before each file operation is 
initiated. As a minimum you must ensure that the block is a valid FAB 
(BID and BLN fields contain the proper values) and that the FAB IFI 
field contains the value returned by RMS-11 when the file was created 
or opened. This value is the pointer to the IFAB. You should also 
set the FAB's fields to the values appropriate to the file operation 
you are preparing for: do not assume that the fields contain the va- 
lues you set before the last use. 



1.2.1.1 Allocation - Each FAB must be allocated at assembly time. 
The minimum syntax is: 

.EVEN 

label: FAB$B 

FAB$E 

where label is the name of the FAB and not necessarily the name of the 
file associated with the FAB. 

The FAB$B macro allocates space for the FAB, and the FAB$E macro 
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Table 1-3: File Access Block Fields 



Field 


Field 


Default 


Description 


Name 


Size 






ALQ 


2W 





Size of file 


BID 


IB 


N/A 


FAB identifier 


*BKS 


IB 


1 record 


Bucket size 


BLN 


IB 


N/A 


RAB length 


*BLS 


1W 





Block size 


BPA 


1W 





Location of private I/O buffer 


BPS 


1W 





Size of private I/O buffer 


CTX 


1W 





Available to user 


*DEQ 


1W 





Automatic extension quantity 


DEV 


IB 


N/A 


Device characteristics 


DNA 


1W 





Location of filespec defaults 


DNS 


IB 





Size of filespec defaults 


FAC 


IB 


FB$GET 


Types of record operations 


FNA 


1W 





Location of filespec 


FNS 


IB 





Size of filespec 


FOP 


1W 





File processing options 


*FSZ 


IB 





Size of fixed area for VFC 


IFI 


1W 


N/A 


Pointer to IFAB 


LCH 


IB 





Logical channel 


*MRN 


2W 





Maximum Record Number 


*MRS 


1W 





Maximum Record Size 


NAM 


1W 





Pointer to NAM Block 


*ORG 


IB 


FB$SEQ 


File organization 


*RAT 


IB 





Record attributes 


*RFM 


IB 


FB$VAR 


Record format 


RTV 


IB 





Window size 


*RTV 


IB 





Clustersize 


SHR 


IB 





File sharing 


STS 


1W 


N/A 


Completion code 


STV 


1W 


N/A 


More error information 


XAB 


1W 





Pointer to first XAB 



*File attribute 



1.2.1.2 Initialization - The value stored in a FAB field by the FAB$E 
macro is determined by an initialization macro, or in its absence, an 
RMS-11 default for the field (see "Initialization and Default" in the 
individual sections on the fields in Chapter 3). 
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If you want a field to contain a value other than its default value, 
you must specify its initialization macro between the FAB$B and FAB$E 
macros*. Initialization macros have the general form: 

F$fnm arg 

where fnm is the three-letter field name, such as ALQ, MRN, and so on, 
and 

arg is one or more arguments specifying the value (s) to be en- 
tered in the indicated field; arg can be a: 

• symbolic value, such as FB$PUT (representing put opera- 
tions) , in the form FB$nam; symbolic values are joined 
together with exclamation points (!). 

• label, that is, the MACRO-11 term for the name of an ad- 
dress in the program, such as the start of a buffer. 

• numeric value, such as maximum record size, specifying 
the number of bytes, characters, blocks, and so on. 

Cautions: 

• Because initialization macros operate at assembly time, you cannot 
use global symbols or labels as arguments. All symbols and labels 
must be defined locally, that is, in the same module with the ma- 
cros. 

• The default radix for numeric values in initialization macros is 
decimal . 



1.2.2 Record Access Block (RAB) 

A Record Access Block, abbreviated RAB, represents a Record Access 
Stream during the execution of record operation macros: 

$CONNECT 

$DELETE 

$DISCONNECT 

$FIND 

$GET 

$PUT 

$UPDATE 

$REWIND 

$TRUNCATE 

$FLUSH 

$NXTVOL 

The RAB not only completely describes the format of the records in- 
volved, but also all other aspects of record operations. 
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*The value of any field can also be set at run time by the field ac- 
cess macros $SET and $STORE; see Chapter 7. 
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RAB fields (listed in Table 1-4) must contain the proper values before 
the stream is set up (via the $CONNECT macro) and before record opera- 
tions are initiated, but they can be changed after each operation is 
complete because RMS-11 has transferred the pertinent information 
about the stream to an internal (nonvisible) structure called an 
Internal Record Access Block (IRAB) . 

Therefore, one RAB may be used to represent any number of streams as 
long as the RAB is changed appropriately before each record operation 
is initiated. As a minimum you must ensure that the block is a valid 
RAB (BID and BLN fields contain the proper values) and that the RAB 
ISI field contains the value returned by RMS-11 when the stream was 
connected to a file. This value is the pointer to the IRAB. You 
should also set the RAB ' s fields to the values appropriate to the re- 
cord operation you are preparing for: do not assume that the fields 
contain the values you set before the last use. 



1.2.2.1 Allocation - Each RAB must be allocated at assembly time. 
The minimum syntax is: 

.EVEN 

label: RAB$B [type] 

RAB$E 

where label is the name of the RAB, and 

type indicates if the program will attempt asynchronous I/O op- 
erations using the RAB (see Chapter 1), with one of the 
following values: 

SYN means synchronous record operations only 

ASYN means both synchronous and asynchronous record 
operations 

The RAB$B macro allocates space for the RAB, and the RAB$E macro 
stores values in the individual RAB fields and terminates the defini- 
tion of the block. 



1.2.2.2 Initialization - The value stored in a RAB field by the RAB$E 
macro is determined by an initialization macro, or in its absence, an 
RMS-11 default for the field (see "Initialization and Default" in the 
individual sections on the fields). 

If you want a field to contain a value other than its default value, 
you must specify its initialization macro between the RAB$B and RAB$E 
macros*. Initialization macros have the general form: 



*The value of any field can also be set at run time by the field ac- 
cess macros $SET and $STORE; see Chapter 7. 
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R$fnm arg 

where fnm is the three-letter field name, such as KBF, RAC, and so on 

arg is one or more arguments specifying the value (s) to be en- 
tered in the indicated field; arg can be a: 

• symbolic value, such as RB$KEY, specifying a random re- 
cord operation, in the form RB$nam; two or more symbol- 
ic values are joined together with exclamation points 
(!) . 

• label, that is, the MACRO-11 term for the name of an ad- 
dress in the program, such as the start of a buffer. 

• numeric value, such as maximum record size, specifying 
the number of bytes, characters, blocks, and so on. 



Cautions; 

• Because initialization macros operate at assembly-time, you cannot 
use global symbols or labels as arguments. All symbols and labels 
must defined locally, that is, in the same module with the macros. 

• The default radix for numeric values in initialization macros is 
decimal . 



Table 


1-4: Record Access 


Block Fields 




Field 


Field 


Default 


Description 




Name 


Si ze 








BID 


IB 


N/A 


RAB identifier 




BKT 


2W 


None 


Relative record number or 


VBN 


BLN 


IB 


N/A 


RAB length 




CTX 


1W 





User area 




FAB 


1W 





FAB address 




ISI 


1W 


N/A 


Pointer to IRAB 




KBF 


1W 





Key buffer address 




KRF 


IB 





Key of reference 




KSZ 


IB 





Key buffer size 




MBC 


IB 





Multiblock count 




MBF 


IB 





Multibuffer count 




RAC 


IB 





Record Access Mode 




RBF 


1W 





Address of output record 




RFA 


3W 





Record's File Address 




RHB 


1W 





Fixed control area buffer 




ROP 


1W 





Record processing options 




RSZ 


1W 





Size of output record 




STS 


1W 


N/A 


Completion status code 




STV 


1W 


N/A 


Status value 




UBF 


1W 





Input record buffer 




USZ 


1W 





Input record buffer size 
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1.2.3 Extended Attribute Block (XAB) 

An Extended Attribute Block, abbreviated XAB, is an extension of the 
File Access Block for an RMS-11 file. An XAB represents one of the 
following during file operations: 

Area (Indexed only) 

Key (Indexed only) 

Date-time information 

Protection information 

Summary information (Indexed only) 

XABs are generally required only when a file is created, particularly 
if the file is Indexed, or when the $DISPLAY macro is used to retrieve 
information about a file. 

XAB fields (listed by XAB type in Chapter 5) must contain the proper 
values before the operation is initiated, but they may be changed 
after each operation is complete because RMS-11 has transferred the 
pertinent information about the file to the appropriate IFAB. 



1.2.3.1 Allocation - Each XAB must be allocated at assembly time. 
The minimum syntax is: 

.EVEN 
label: XAB$B type 
XAB$E 

where label is the name of the XAB, and 

type indicates the type of information contained in the XAB and 
therefore its structure and fields, with one of the fol- 
lowing values: 

XB$ALL the XAB defines a file area 

XB$DAT the XAB contains date-time information 

XB$KEY the XAB defines a key for an Indexed file 

XB$PRO the XAB specifies file protection information 

XB$SUM the XAB contains summary information about an 
Indexed file 

A type must be specified, or the MACRO assembler will gen- 
erate an error. 

The XAB$B macro allocates space for the XAB, and the XAB$E macro 
stores values in the individual XAB fields, including the type symbol- 
ic value in the COD field, and terminates the definition of the block. 
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1.2.3.2 Initialization - The value stored in an XAB field by the 
XAB$E macro is determined by an initialization macro, or in its ab- 
sence, an RMS-11 default for the field (see "Initialization and De- 
fault" in the individual sections on the fields) . 

If you want a field to contain a value other than its default value, 
you must specify its initialization macro between the XAB$B and XAB$E 
macros*. Initialization macros have the general form: 

X$fnm arg 

where fnm is the three-letter field name, such as IAN, RDT, and so on 

arg is one or more arguments specifying the value (s) to be en- 
tered in the indicated field; arg can be a: 

• symbolic value, such as XB$NUL, representing null key 
specification, in the form XB$nam; two or more symbolic 
values are joined together with exclamation points (!). 

• label, that is, the MACRO-11 term for the name of an ad- 
dress in the program, such as the start of a buffer. 

• numeric value, such as fill number, specifying the 
number of bytes, characters, blocks, and so on. 

Cautions: 

• Because initialization macros operate at assembly-time, you cannot 
use global symbols or labels as arguments. All symbols and labels 
must be defined locally, that is, in the same module with the ma- 
cros. 

• The default radix for numeric values in initialization macros is 
decimal . 



1.2.3.3 Linking and Ordering XABs - Whenever you want to include Ex- 
tended Attribute Blocks in a file operation, you must link them with 
the File Access Block and with each other. This linking is done with 
pointers, addresses stored in the FAB XAB field and then in each' of 
the XAB NXT fields; the end of the chain is indicated by a zero NXT 
field. 



1.2.3.3.1 Ordering by Type of XAB - Within a chain of XABs, RMS-11 
does not require any ordering by type, that is, the contents of the 
COD field. 



*The value of any field can also be set at run time by the field ac- 
cess macros $SET or $STORE; see Chapter 7. 
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Example To determine the attributes of a single-key Indexed file, 
allocate, at assembly time, one each: 



Type 

Date XAB 
Key XAB 

Protection XAB 
Summary XAB 



Label 

DATXAB 
KEYXAB 
PROXAB 
SUM XAB 



You can link these blocks together in several ways; two of 
them are: 

1. At assembly time, with initialization macros: 

.EVEN 
DSPFAB: FAB$B 



X$XAB DATXAB 

FAB$E 

DATXAB: XAB$B XB$DAT 

X$NXT KEYXAB 

XAB$E 

KEYXAB: XAB$B XB$KEY 

X$NXT PROXAB 

XAB$E 

PROXAB: XAB$B XB$PRO 

X$NXT SUM XAB 



POINT TO FIRST XAB 



POINT TO NEXT XAB 



POINT TO NEXT XAB 



POINT TO NEXT XAB 



XAB$E 
SUMXAB: XAB$B XB$SUM 



XAB$E 
2. At run time, with the $STORE macro: 



MOV #DSPFAB,R4 

$STORE #SUMXAB,XAB,R4 ; 

MOV #SUMXAB,R4 

$STORE #KEYXAB,NXT, R4 

MOV #KEYXAB,R4 

$STORE #DATXAB,NXT,R4 

MOV #DATXAB,R4 

$STORE #PR0XAB,NXT,R4 

MOV #PROXAB,R4 

$STORE #0,NXT,R4 



PUT FAB ADDRESS IN R4, AS 

REQUIRED 

MAKE DIFF XAB 1ST IN 

CHAIN 
PUT XAB ADDRESS IN R4 
LINK IN NEXT XAB 
PUT XAB ADDRESS IN R4 
LINK IN NEXT XAB 
PUT XAB ADDRESS IN R4 
LINK IN NEXT XAB 
PUT XAB ADDRESS IN R4 
LINK IN NEXT XAB 



Finally, you issue a $DISPLAY macro (see Chapter 8) and 
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RMS-11 fills the XAB chain with attribute information, set- 
ting fields in accordance with the COD field of each block. 



1.2.3.3.2 Ordering Within XAB Type - Multiple instances of Key and 
Allocation XABs must be linked: 

• In ascending order by contents of a numbering field, that is, the 
REF and AID fields respectively 

• Logically contiguous, that is, there can be no XABs of other types 
within a series of Key or Allocation XABs 

• Densely for the $CREATE operation, that is, the XABs must be num- 
bered 1, 2, 3, and so on; by contrast, the numbering for $DISPLAY, 
$EXTEND, and $OPEN does not have to be dense; that is, you can se- 
lect only certain keys or areas whose attributes you want set 



1. 2. 4 Name Block 

A Name Control Block, abbreviated NAM, contains system-specific infor- 
mation about a file, including: 

Full File Specification 

An ASCII string representing RMS-ll's merger of: 

• the primary file name string described by the FAB FNA and 
FNS fields 

• the default name string described by the FAB DNA and DNS 
fields 

• the system defaults 

File ID 

An index that the file processor can use to locate a file 
without consulting directories; must be used with device 
ID. 

Device ID 

An indicator for the device containing the file; must be 
used with file ID. 

RMS-11 provides this information in NAM Block fields (listed in Table 
1-5) during create and open operations and uses this information as 
input during erase and open operations. 

You indicate the existence of a NAM Block for these services by set- 
ting the FAB NAM field to the address of a properly allocated NAM 
Block. NAM Block fields must contain the proper values before the op- 
eration is initiated, but they may be changed after the operation is 
complete . 



1-16 Using RMS-11 in a MACRO-11 Progr 



am 



wmfmmmmmm 



1.2.4.1 Allocation - Each NAM Block must be allocated at assembly 
time. The minimum syntax is: 

.EVEN 

label: NAM$B 

NAM$E 

where label is the name of the NAM Block. 

The NAM$B macro allocates space for the NAM, and the NAM$E macro 
stores values in the individual NAM fields and terminates the defini- 
tion of the block. 



1.2.4.2 Initialization - The value stored in a NAM field by the NAM$E 
macro is determined by an initialization macro, or in its absence, an 
RMS-11 default for the field (see "Initialization and Default" in the 
individual sections on the fields) . 
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If you want a field to contain a value other than its default value, 
you must specify its initialization macro between the NAM$B and NAM$E 
macros*. Initialization macros have the general form: 

N$fnm arg 

where fnm is the three-letter field name, such as ESA, ESL, and so on, 
and 

arg is one or more arguments specifying the value (s) to be en- 
tered in the indicated field; arg can be a: 

• label, that is, the MACRO-11 term for the name of an ad- 
dress in the program, such as the start of a buffer. 

• numeric value, such as expanded string size, specifying 
the number of bytes. 

Cautions: 

• Because initialization macros operate at assembly time, you cannot 
use global symbols or labels as arguments. All symbols and labels 
must be defined locally, that is, in the same module with the ma- 
cros. 

• The default radix for numeric values in initialization macros is 
decimal . 



*The value of any field can also be set at run time by the field ac- 
cess macros $SET and $STORE; see Chapter 7. 
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Table 1-5: NAM Block Fields 



Field 


Field 


Default 


Description 


Name 


Si ze 






DVI 


1W 





Device ID 


ESA 


1W 





Expanded string address 


ESL 


IB 





Expanded string length 


ESS 


IB 





Expanded string size 


FID 


IB 





File ID 



1.3 CONTROL BLOCK FIELD ACCESS AT RUN TIME 

RMS-11 field access macro retrieve, modify, and test the contents of 
fields in the RMS-11 control blocks, FABs , RABs , and XABs , at run 
time. These macros enable you to treat the control block fields as 
logical entities, without regard for the placement of the fields with- 
in the control blocks and to a large degree, for the sizes of the 
fields. 



Table 1-6 contains a summary of the available macros. Each macro 
also described in a separate section of Chapter 7. 
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Table 1-6: RMS-11 Field Access Macros 



Macro Name 


Field Size 


Function 


$COMPARE 


1 byte or 1 word 


Compares the contents of a field 
with a value you specify. 


$FETCH 


Any size 


Copies the contents of a field into 
a location you specify. 


$OFF 


1 byte or 1 word 


Resets one or more bits within a 
bit string field. 


$SET 


1 byte or 1 word 


Sets one or more bits within a bit 
string field. 


$STORE 


Any size 


Copies the contents of a location 
you specify into a field. 


$TESTBITS 


1 byte or 1 word 


Tests one or more bits within a bit 
string field. 
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NOTE 

RMS-11 assumes octal radix for all numeric values used as 

operands for the field access macros. You indicate decimal 

radix with an explicit decimal point following a numeric 
value . 
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1.4 FILE AND RECORD OPERATIONS 

You use the RMS-11 file and record operation macros to access and man- 
ipulate files and records within files. These macros combine with the 
control blocks (Chapters 3 through 6) to form your program's run-time 
interface with RMS-11. 

Before executing one of these macros, your program sets values in a 
control block's fields, then specifies the block as an argument to the 
macro. The macro initiates all processing involved with the indicated 
RMS-11 operation. During the operation, RMS-11 returns information 
about the processing in fields of the associated control block. 

If you do not initialize or set fields, relying on defaults, RMS-11 
changes the fields to contain the default or minimum values as output 
from the operation. 

See the RMS-11 User's Guide for a description of the operations them- 
selves. 

While differing in function, the file and record operation macros use 
the same general format and calling sequence. Within the calling se- 
quence, you identify the control block associated with the operation 
and optional completion routines. 

Before your program initiates a file or record operation macro, it 
must: 

1. Ensure that the appropriate values are set in the fields used by 
RMS-11 during the operation. You do this with either initializa- 
tion macros (see Chapters 3, 4, and 5) or field access macros (see 
Chapter 7 ) . 

2. Execute the correct calling sequence. 



1.4.1 Completion Routines 

You can write subroutines that RMS-11 executes as an extension of a 
file or record operation macro. These completion routines can be used 
after the successful completion or after error termination of an oper- 
ation. 

RMS-11 invokes a completion routine if you supply an address at the 
appropriate point in the calling sequence for the operation. At the 
end of the completion routine, RMS-11 restores the stack and other 
parameters and returns control to your program at the point after the 
macro was initiated. 

The use of completion routines is always optional. However, if you do 
not use completion routines, your program should check the value of 
the associated block's STS field after the macro has been executed. 
If the status code is negative, an error occurred during the opera- 
tion. If the status code is positive, the operation was successful, 
although an STS value greater than one indicates qualified success. 
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See Appendix A for a description of the completion codes, 
field should never contain zero after an RMS-11 operation. 



The STS 



When using completion routines, 
the following areas: 



you must be aware of conventions in 



Register Usage 

General register R5 contains the address of the same argu- 
ment list or a copy of the argument list, that was part of 
the calling sequence to the RMS-11 operation (see Section 
8.0.2). Therefore, you can use the control block address at 
2(R5) to access fields in the control block. 

RMS-11 Operations within Completion Routines 

A completion routine can execute file and record operation 
macros. Each operation is an extension of the original op- 
eration that caused the completion routine to be used. See 
Appendix A of the RMS-11 User's Guide for restrictions on 
this capability in the RMS-11 Asynchronous Environment.} 



To return control from 
must do the following: 



a completion routine to RMS-11, your program 



1. Restore the stack pointer (SP) to its value at the beginning of 
the completion routine. Your program must not attempt to cause 
control flow changes by modifying the stack. 

2. Execute a $RETURN macro, in the form: 

$RETURN 

This macro requires no arguments and denotes the end of a comple- 
tion routine. 



1.4.2 Calling Sequence 

Each file and record operation macro requires a word-aligned formatted 
argument list. Your program can construct this list or allow RMS-11 
to build it. Generally, your program generates less code and use less 
stack to build the list than does RMS-11. 



1.4.2.1 Your Program Supplies the Argument List - If your program 
constructs the argument list, it executes RMS-11 file and record oper- 
ations with the following sequence: 
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The program constructs the argument list in the following form, 
with the arguments arranged in the order shown: 



Argument 

Undefined 
Argument Count 



Block Address 
Error Address 
Success Address; 



Size RMS-11 Interpretation 

1 byte Not used. 

1 byte Binary value from 1 through 3 repre- 
senting the number of arguments to 
be used from the argument list. 
This field equals 1 if you do not 
supply completion routine addresses. 

1 word Address of a FAB for file operations 
or a RAB for record operations. 

1 word Address of a completion routine you 
want called if the operation fails. 

1 word Address of a completion routine you 
want called if the operation com- 
pletes successfully. Not used by 
file operation macros. 

2. Store the address of the argument list in general register R5. 

3. Execute the file or record operation macro without arguments, in 
the form: 

$macnam 

4. If completion routines were specified, continue processing because 
success and/or failure has been tested and handled. Otherwise, 
check the STS field of the associated control block. 



Example The following code constructs an argument list and uses it 
to execute a get operation: 

MOV #LIST,R5 ; ADDRESS OF ARGUMENT LIST 
$GET ;READ A RECORD FROM THE FILE 



Example 



LIST: .WORD 3 ;NUMBER OF ARGUMENTS 

RECORD ACCESS BLOCK ADDRESS 
ERROR ROUTINE ADDRESS 
SUCCESS ROUTINE ADDRESS 

The following code constructs an argument list specifying a 
success completion routine, but no error completion routine: 



WORD 


3 


WORD 


INRAB 


WORD 


ERR1 


WORD 


SUCC1 



LIST: 



WORD 


3 


WORD 


INRAB 


WORD 


-1 


WORD 


SUCC1 



;N0 ERROR ROUTINE 
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Example The following code constructs an argument list specifying 
error and success routines, but the program determines be- 
fore the operation is initiated that neither routine 
appl ies: 



MOV #1,LIST 

MOV #LIST,R5 

$GET 

$COMPARE #0,STS,2(R5) 

BGT NXTSTP 



SHRINK SIZE OF LIST 
ADDRESS OF ARGUMENT LIST 
READ A RECORD FROM THE FILE 
LOOK AT STATUS CODE 
SUCCESS 



GETERR; 



LIST: 



WORD 


3 


WORD 


INRAB 


WORD 


ERR1 


WORD 


SUCC1 



NUMBER OF ARGUMENTS 
RECORD ACCESS BLOCK ADDRESS 
ERROR ROUTINE ADDRESS 
SUCCESS ROUTINE ADDRESS 



1.4.2.2 RMS-11 Generates the Argument List - Your program can execute 
RMS-11 file and record operation macros with the form: 

$macnam block[ , error [ ,success] ] 

where block is the address of a FAB for file operations or a RAB for 
record operations. 

error is the address of a completion routine you want called if 
the operation fails. 

success is the address of a completion routine you want called if 
the operation completes successfully. Not used by file 
operation macros. 

The macro builds an argument list on your program's stack from the in- 
formation provided. Then it initiates the processing appropriate to 
the indicated operation. After the macro is executed, your program 
should check the STS field of the associated block unless completion 
routines were specified. 



1.4.3 File Operation Macros 

A file operation macro causes RMS-11 to perform an action related to 
an entire file. The macro name indicates the type of operation per- 
formed. The fields of the FAB associated with the macro in the cal- 
ling sequence identifies the file and qualifies the operation. 

Table 1-7 summarizes the RMS-11 file operation macros. 
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Table 1-7: RMS-11 File Operation Macros 



Macro Name 



Description 



$ CLOSE 

$CREATE 

SD I SPLAY 

$ERASE 

$EXTEND 

$OPEN 



Closes an open RMS-11 file so that your program can no 
longer access its contents. 

RMS-11 creates and opens an RMS-11 file as described by 
the associated FAB and XABs, if any. 

Stores attributes of an existing RMS-11 file in FAB and 
XAB fields. 

Deletes an existing RMS-11 file and removes its entry(s) 
from a directory. 

Increases the number of blocks allocated to an RMS-11 
file. 

Opens an existing RMS-11 file, making its contents ava- 
ilable for processing. 



1.4.4 Record Operation Macros 

After it has created or opened an RMS-11 file, your program can per- 
form record operations on it. These operations involve the following 
concepts that are explained in the RMS-11 User's Guide and Chapter 1 

of this manual. 

Record Access Streams 

File sharing 

Context, Current Record, and Next Record 

Synchronous and asynchronous record operations 

Table 1-8 summarizes the RMS-11 record operation macros. 



1.5 CREATING THE TASK 

After you have written a MACRO-11 program as described in this 
chapter, you must assemble each module with the following reference in 
your command string: 

LB : [1,1] RMSMAC . MLB/ML 

After you have assembled all modules in your program successfully, you 
must link the modules with the RMS-11 routines using the Task Builder 
utility supplied with your operating system. You can link the RMS-11 
routines in your task without overlays or with disk-resident or 
memory-resident overlays. See the RMS-11 User's Guide for a discus- 
sion of these options. 
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NOTE 



Do not use the /SQ switch with the Task Builder, 
quires PSECTS to be in alphabetical order. 



RMS-11 re- 



Table 1-8: RMS-11 Record Operation Macros 



Macro Name 



Description 



$CONNECT 
$DELETE 

$DISCONNECT 

$FIND 

$FLUSH 

$FREE 

$GET 

$NXTVOL 

$PUT 

$REWIND 

$TRUNCATE 

$UPDATE 

$WAIT 



Establishes a Record Access Stream. 

Deletes a record from an RMS-11 Relative or Indexed 
file. 

Terminates a Record Access Stream. 

Locates a record in an RMS-11 file. 

Moves all data in unwritten I/O buffers to disk. 

Unlocks a bucket locked by a Record Access Stream. 

Moves a record from an RMS-11 file into your program's 
user buffer. 

Continues processing with the next volume of magnetic 
tape multivolume set. 

Moves a record from your program's user buffer to an 
RMS-11 file. 

Resets a Record Access Stream's context to the logical 
beginning of an RMS-11 file. 

Deletes record at the end of an RMS-11 Sequential 
file. 

Replaces a record in an RMS-11 file with a record from 
your program's user buffer. 

Suspends processing until an RMS-11 asynchronous re- 
cord operation completes. 
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CHAPTER 2 
PROVIDING BUFFER SPACE 



2.1 CENTRAL BUFFER POOL 

The central buffer pool must be allocated at assembly time with the 
series of macros and arguments described in this section and Table 
2-1. The macro series must start with the POOL$B macro and end with 
the POOL$E macro. 

You can use multiple buffer pool allocations among the program modules 
that you link together with the Task Builder utility. The Task Build- 
er sums the size requirements indicated by all buffer pool declara- 
tions. 



Table 2-1: Buffer Pool Declaration Macros 



Macro 


Description 


Required 


POOL$B 


Beginning of buffer pool declaration 


Yes 


P$BDB 


Number of Buffer Descriptor Blocks 


Yes 


P$FAB 


Number of files open simultaneously 


Yes 


P$RAB 


Number of nonlndexed streams 


If Sequential or 




connected simultaneously 


Relative files 


P$RABX 


Number of Indexed streams 
connected simultaneously 


If Indexed files 


P$IDX 


Number of defined keys 


If Indexed files 


P$BUF 


Input/output buffer requirements 


If no BPA or GSA 


POOL$E 


End of buffer pool declaration 


Yes 



************* 

* * 

REQUIRED * P$BDB * 

* * 

************* 



2.1.1 P$BDB 

The P$BDB macro ensures that the buffer pool contains sufficient space 
for internal RMS-11 control structures known as Buffer Descriptor 
Blocks (BDBs) . 

General form: 

P$BDB nbrbdbs 

where nbrbdbs is a numeric value or symbol representing the number of 
Buffer Descriptor Blocks required to support the file 
processing performed by your program. 

To determine this value, use the following equation: 

nbrbdbs = maxbuf + maxrel + (2 * maxidx) 

where maxbuf is the count of the I/O buffers that can be used simul- 
taneously, that is, the maximum number of I/O buffers 
ever in use for simultaneously open files. 

You calculate this value by totaling the multibuffer 
counts in the MBF fields of RABs for all combinations of 
simultaneously connected Record Access Streams. The max- 
imum value among all such combinations is the desired 
maxbuf value. RMS-11 must allocate one BDB for each I/O 
buffer being used at one time. 

maxrel is the maximum number of Record Access Streams ever con- 
nected simultaneously for put operations to Relative 
files (whether or not an actual put operation is per- 
formed) . RMS-11 allocates one BDB for each stream con- 
nected to a Relative file. 

maxidx is the maximum number of Record Access Streams ever ac- 
tive simultaneously for put operations to Indexed files 
(whether or not an actual put operation is performed) . 
RMS-11 allocated one BDB for each stream connected to an 
Indexed file. 
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************* 

* * 

REQUIRED * P$FAB * 

* * 
************* 



2.1.2 P$FAB 

The P$FAB macro ensures that the buffer pool contains sufficient space 
for internal RMS-11 control structures related to File Access Blocks 
(FABs) . 

General form: 

P$FAB number 

where number is a numeric value or symbol representing the maximum 
number of files that are open simultaneously at run time. 
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************* 

* * 

* P$RAB * 

* * 

************* 



2.1.3 P$RAB 

The P$RAB macro ensures that the buffer pool contains sufficient space 
for internal RMS-11 control structures related to Record Access Blocks 
(RABs) for Sequential and Relative files. You can omit this pool 
macro if your program does not perform record operations on Sequential 
or Relative files. 

General form: 

R$RAB number 

where number is a numeric value or symbol representing the maximum 
number of RABs that your program connects simultaneously 
to Sequential and Relative files. 
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************* 

* * 

* P$RABX * 

* * 
************* 



2.1.4 P$RABX 

The P$RABX macro ensures that the buffer pool contains sufficient 
space for internal RMS-11 control structures related to Record Access 
Blocks (RABs) for Indexed files. You can omit this pool macro if your 
program does not perform record operations on Indexed files. 

General form: 

P$RABX rabs,keysiz f nbrkeys 

where rabs is a numeric value or symbol representing the maximum 
number of Record Access Streams that your program connects 
to Indexed files simultaneously. 

keysiz is a numeric value or symbol representing the size, in 
bytes, of the largest key field that can be accessed by one 
of the streams. 

nbrkeys is a numeric value or symbol representing the number of 
keys that can change values during an update operation on 
an Indexed file. You must specify this value whenever your 
program creates or opens an Indexed file with FB$UPD set in 
the FAB FAC field. 

Example The following code indicates that there will be at most one 
stream connected to an Indexed file at any point during pro- 
gram execution. The largest key field in any such file is 
32 bytes and no keys can change during update operations. 

POOL$B ;BEGIN POOL DECLARATION 

P$RABX 1,32 ;ONE FILE AND BIGGEST KEY, NO CHANGES 

POOL$E ;END POOL DECLARATION 
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************* 

* * 

* P$IDX * 

* * 

************* 



2.1.5 P$IDX 

The P$IDX macro ensures that the buffer pool contains sufficient space 
for internal RMS-11 control structures containing summary information 
about an Indexed file's keys. You can omit this pool macro if your 
program does not open Indexed files. 

General form: 

P$IDX number 

where number is a numeric value or symbol representing the total 
number of keys defined for all Indexed files open simul- 
taneously. Include all keys even if they are never used 
for find or get operations. 
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************* 

* * 

* P$BUF * 

* * 

************* 



2.1.6 P$BUF 

The P$BUF macro ensures that the buffer pool contains sufficient space 
for the I/O buffers required by your program. You can omit this macro 
only if you are providing private buffers for all files or a GSA rou- 
tine. 

General form: 

P$BUF iosiz 

where iosiz is a numeric value or symbol representing the total bytes 
<-j required for I/O buffers by your program. To calculate this number, 

^"^ use the following equation and round the result up to a multiple of 

four. 

iosiz = strmszl + strmsz2 + ... + strmszn 
where iosiz is the total I/O buffer requirement, and 

strmszl are the I/O buffer space requirements (in bytes) for the 
Record Access Streams associated with the file that are 
^m? strmszn active simultaneously. 

You calculate the requirements for each stream as follows: 

• For Sequential files on disk: STRMSZ = 512*MBC 

• For Sequential files on magnetic tape: STRMSZ = BLS 

where BLS is the size, in characters, of each physical block of the 
i^j magtape file, that is, the value contained in the BLS field of the 
^"^ FAB, and 

MBC is the value contained in the MBC field of the RAB associated 
with the stream. 

• For Relative files: STRMSZ = BKS*512 

where BKS is the number of blocks in a bucket of the file (from the 

FAB BKS fields) . 

• For Indexed files: STRMSZ = BKS*MBF*512 

where BKS is the number of blocks in the largest bucket of the file 
(selected from the FAB BKS and the Allocation XAB BKZ fields) , and 

MBF is the value contained in the MBF field of the RAB associated 
^"^ with the stream. 
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2.2 GET SPACE ROUTINE 

A Get Space routine gives you complete control over the allocation of 
buffer space in your task. A single GSA routine serves all files used 
by the program. 

RMS-11 uses the GSA routine when it requires or releases space. When 
RMS-11 requests space, it expects one of two outputs from your 
routine: 

• the low-byte address of a contiguous block of bytes at least as big 
as that requested. 

• an error indication that space is not available. RMS-11 issues an 
ER$DME message and returns control to the program. 

When RMS-11 releases space, it expects no output from your routine; 
it assumes that the release of space was successful if the routine 
terminates successfully. 

NOTES 

• Your routine must start on a word boundary: precede the 
label defining the routine's starting address with a 
.EVEN directive. 

• RMS-11 trusts your routine: it performs no parameter 
checking when the routine finishes and therefore can be 
lead into an error or even fatal situation if the routine 
did not allocate space properly. 



2.2.1 Specifying a Routine 

You can specify the starting address of your GSA routine at assembly 
time or at run time. Either way, your routine is used only when the 
internal address maintained by RMS-11 is not zero. Your program can 
also query RMS-11 at run time for the Get Space Address it is using. 



2.2.1.1 Specifying a Get Space Address at Assembly Time - 

General form: 

GSA$ label 

where label is the name of your GSA routine as specified in the label 
field of a source line and followed by a colon. 

Example GSARTN: 

RTS PC 
GSA$ GSARTN 
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2.2.1.2 Specifying a Get Space Address at Run Time - 
General form: 

$SETGSA argument 

where argument is suitable as an operand for a MOV instruction. Where 

you use label with the $GSA macro, you use #label with 
the $SETGSA macro. You cannot use R6 as an argument; 
the assembler returns the error message: 

.ERROR ; R6 MUST BE RO - R5; 

Example GSARTN: 

RTS PC 

* 

$SETGSA #GSARTN 
Example $SETGSA R5 
Example $SETGSA 10 (SP) 
Example $SETGSA 10 (R3) 

2.2.1.3 Retrieving a Get Space Address at Run Time - 

General form: 

$GETGSA 

RMS-11 sets general register RO equal to the Get Space Address it has 
stored internally. If you have not executed a GSA$ or $SETGSA macro, 
this value is 0. 

2.2.2 Interfaces to Routines 

The following subsections describe the interfaces between RMS-11 and 
your GSA routine as well as the format of RMS-11 pool block headers. 

RMS-11 sets a value in general register 2 (R2) to indicate whether: 

• space should be allocated for an operation (R2 = 0) 

• space is being returned after an operation (R2 <> 0) 

The GSA routine is analogous to the $RQCB/$RLCB request and release 
core blocks routine as far as RMS-11 is concerned; the interfaces are 
identical. See also "Comments" below. 
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2.2.2.1 RMS-11 Request For Space - RMS-11 calls the routine with the 
following inputs: 

RO = address of RMS-11 Pool List Head 

Rl = amount of space requested (in bytes) 

R2 = 

RMS-11 expects the following outputs from the user routine: 

If C-bit = 0, all bytes requested have been allocated and 
RO = address of allocated block 

If C-bit = 1, space was not available 

General registers R3, R4, R5, and R6 and the stack must contain the 
same values when the user routine finishes as they did when it was 
called. 



2.2.2.2 RMS-11 Release Of Space - RMS-11 calls the routine with the 
following inputs: 

RO = address of RMS-11 Pool List Head Block 

Rl = size in bytes of block being released 

R2 = address of block being released 

No outputs are expected: the user routine must complete the release; 
however, general registers R3, R4, R5, and R6 and the stack must con- 
tain the same values when the routine finishes as they did when it was 
called. 



2.2.2.3 RMS-11 Pool Block Header Formats - The RMS-11 buffer pool is 
actually subdivided into pools for each of the different sized inter- 
nal structures that RMS-11 must maintain: 

Buffer Descriptor Blocks 
Key Descriptor Blocks 
Internal FABs and RABs 
I/O Buffers 
Key Buffers 

Each of these pools is described with a Pool List Head that points to 
the first free contiguous block of bytes within the pool. 

Within all pools, space is divided into contiguous sections of bytes 
called blocks. Each block starts with a block header containing a po- 
inter to the next free block in the pool and its own size in bytes. 

Each pool is therefore accessed via the Pool List Head (which points 
to the first free block), then via a linked series of block headers 
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(which point to the next free block as well as tell how many bytes are 
in the block) . 



RMS-11 Pool List Head Block: 

< — (RO) 

I I 

I value I 

I I 

2 

I I 

I I 

I I 

4 

• if value = 0, there is no available space left in the pool des- 
cribed by this List Head 

• if value <> 0, value points to the first available pool block 
header 



RMS-11 Pool Block Header: 

, o 

I I 

I value I 

I I 

, 2 

I I 

I size I 

I I 
.__ 4 

where value is either zero (0) or not: 

« if value = 0, this is the last available block in this 
pool 

<» if value <> 0, value points to the next available pool 
block 

size is the size in bytes of this pool block including the 
four-byte header 



2.2.3 Comments 

• You must write the GSA routine and include it in the program. The 
referenced routine is NOT part of RMS-11. 

• Your routine does not have to use the RMS-11 Pool List Head Block, 
but is responsible for its upkeep if it does. 
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SARTN: TST 


R2 


BNE 


2$ 


JMP 


$RQCB 


2$: JMP 


$RLCB 



If your routine does not allocate enough space for the impending 
operation, but signals RMS-11 that it has, the operation will fail 
in an unpredictable manner. 

Since your own routine could fail to allocate enough space and sig- 
nal such failure to RMS-11, causing a dynamic memory error, your 
program should check for the ER$DME error code after every file and 
connect operation. 

Your routine could utilize the system routines $RQCB and $RLCB to 
accomplish the required functions, as follows: 

; CHECK RMS-11 REQUEST 

; RMS-11 WANTS MORE SPACE 

; RMS-11 WANTS TO RETURN SPACE 

The JMP instruction allows the system routine to return directly to 
RMS-11. 

Your routine, when requested to allocate space, could use $RQCB as 
a subroutine (via JSR) to check if enough space is currently avail- 
able: 

— if it is, $RQCB allocates it, returning with the C-bit = 

— if it is not ($RQCB fails; C-bit = 1), your routine could: 

* extend the task 

* cannibalize other pools 

then allocate space out of the new room, set RO as a pointer to 
the allocated buffer, and return to RMS-11. 

The space allocation and release procedures used by your routine 
must be symmetrical. For instance, the system routines $RQCB and 
$RLCB round all sizes up to a multiple of four bytes; these rou- 
tines are symmetrical in that respect. If your routine employs one 
of these procedures, but not the other, the substitute must conform 
to this rounding standard. 
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CHAPTER 3 
FILE ACCESS BLOCK 



The initialization macros (this chapter) and the field access macros 
(Chapter 7) are provided so that you do not have to know the specific 
position and to a large extent, the size of each field in a FAB. You 
can, therefore, treat the fields as logical entities. It is also pos- 
sible that the positions and sizes of the fields will change from re- 
lease to release of RMS-11. 

However, you can determine the position of any field in a FAB as an 
offset from the FAB ' s starting address. RMS-11 represents these off- 
set values with symbols in one of the following forms: 

• 0$fnm 

where fnm is the three-letter name of a one-byte or one-word field; 
fnm is the name used to reference the field in the initialization 
and field access macros. 

Example 0$STS for the status code field 

• 0$fnmx 

where fnm is the name of a multiword field; fnm is the name used 
to reference the field in the initialization and field 
access macros. 

x is a number associated with an individual word in the 
field, from through the end of the field. 

Example 0$ALQO for less significant word and Q$ALQ1 for the more 
significant word in the ALQ field 

The values of these symbols can be found in the symbol table of an as- 
sembly listing file for any module containing the FAB. 
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Field 


Field 


Default 


Description 


Name 


Si ze 






ALQ 


2W 





Size of file 


BID 


IB 


N/A 


FAB identifier 


*BKS 


IB 


1 record 


Bucket size 


BLN 


IB 


N/A 


RAB length 


*BLS 


1W 





Block size 


BPA 


1W 





Location of private I/O buffer 


BPS 


1W 





Size of private I/O buffer 


CTX 


1W 





Available to user 


*DEQ 


1W 





Automatic extension quantity 


DEV 


IB 


N/A 


Device characteristics 


DNA 


1W 





Location of filespec defaults 


DNS 


IB 





Size of filespec defaults 


FAC 


IB 


FB$GET 


Types of record operations 


FNA 


1W 





Location of filespec 


FNS 


IB 





Size of filespec 


FOP 


1W 





File processing options 


*FSZ 


IB 





Size of fixed area for VFC 


IFI 


1W 


N/A 


Pointer to IFAB 


LCH 


IB 





Logical channel 


*MRN 


2W 





Maximum Record Number 


*MRS 


1W 





Maximum Record Size 


NAM 


1W 





Pointer to NAM Block 


*ORG 


IB 


FB$SEQ 


File organization 


*RAT 


IB 





Record attributes 


*RFM 


IB 


FB$VAR 


Record format 


RTV 


IB 





Window size 


*RTV 


IB 





Clustersize 


SHR 


IB 





File sharing 


STS 


1W 


N/A 


Completion code 


STV 


1W 


N/A 


More error information 


XAB 


1W 





Pointer to first XAB 



*File attribute 



iW ^^W HMfc 
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************* 

* * 

* ALQ * 

* * 
************* 



3.1 ALQ 

The two-word Allocation Quantity (ALQ) field contains the size (allo- 
cation quantity) of a disk file, in blocks. RMS-11 ignores the field 
for magnetic tape files. 



3.1.1 Use 

Input to: 

$CREATE 

You set the ALQ field equal to the number of blocks to be 
allocated in the initial extent of the file. 

SEXTEND 

You set the ALQ field equal to the number of blocks to be 
added to the file. 

Output from: 

$OPEN 

RMS-11 sets the ALQ field equal to the virtual block number 
of the last block in the existing file; this is also the 
number of blocks in the file. RMS-11 obtains this informa- 
tion from the file attributes. RMS-11 updates attributes 
during $CREATE and an implicit or explicit file extension. 
RMS-11 uses only the attributes for this information: any 
blocks allocated to the file by non-RMS-11 tasks is essen- 
tially invisible to RMS-11; however, when RMS-11 extends 
the file, those blocks quickly satisfy the request. 

$EXTEND 

RMS-11 sets the ALQ field equal to the number of blocks that 
were added to the file. 



3. 1. 2 Input Values 

$CREATE 

MINIMUM = 0, meaning that the actual size of the file, when it is 
created, depends on the file organization: 

• Sequential files are created with four blocks. 
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• Relative and Indexed files are created with an 
allocation four times bucket size. 

MAXIMUM = number of free blocks on the device containing the 
file; specifying a larger value results in error code 
ER$FUL 

$EXTEND 

MINIMUM = 1, meaning that one block should be added to the file 
(although a zero extent is possible, it is not logi- 
cal) 

MAXIMUM = number of blocks on the device containing the file; 
specifying a larger value results in error code ER$FUL 

For Relative and Indexed files, RMS-11 rounds values up to multiple of 
bucket size. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



3.1.3 Initialization and Default 
Macro takes the form: 

F$ALQ numeric 
where numeric is a number of blocks as discussed under "Values." 
If there is no initialization macro, ALQ = 0. 

3.1.4 Comments 

If Allocation XABs are linked to the FAB, the create and extend opera- 
tions ignore the FAB ALQ field and obtain allocation quantities from 
the XABs; see Chapter 8. However, the open operation works as des- 
cribed . 
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************* 

* * 

* BID * 

* * 
************* 



3.2 BID 

The FAB$B macro sets the one-byte Block Identifier (BID) field to the 
File Access Block identifier, with the symbolic value of FB$BID. 

CAUTION 
DO NOT CHANGE THE BID FIELD. 



3.2.1 Use 

Before RMS-11 uses a FAB during a file operation, it verifies that the 

block is a valid FAB; one of the checks examines the BID field. If 

this field does not contain the proper code, RMS-11 aborts the opera- 
tion with an ER$FAB error code. 
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************* 

* * 

FILE ATTRIBUTE * BKS * 

* * 

************* 



3 . 3 BKS 

The one-byte Bucket Size (BKS) field contains the size of a bucket, in 
disk blocks, for a Relative or Indexed file. The field has no meaning 
for Sequential files. 



3.3.1 Use 

Input to : 

$CREATE 

You set the BKS field equal to the number of disk blocks in 
a bucket for the file to be created, if the ORG field con- 
tains either FB$REL or FB$IDX*. 

Output from: 

$OPEN 

RMS-11 sets the BKS field equal to the bucket size esta- 
blished for the file when it was created, if the ORG field 
contains either FB$REL or FB$IDX*. RMS-11 obtains the in- 
formation from the file attributes. 



3.3.2 Input Values 

MINIMUM = 0, meaning that RMS-11 calculates a size so that a bucket 
contains at least one record. 

MAXIMUM = number of blocks allowed by the operating system (specifying 
a larger value results in error code ER$BKS) : 

IAS = 32 blocks 

RSTS/E = 15 blocks 
RSX-11M = 32 blocks 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



*If the file is Sequential, RMS-11 ignores the field during $CREATE 
and sets it to zero during $OPEN. 
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3.3.3 Initialization and Default 

Macro takes the form: 

F$BKS numeric 

If there is no initialization macro, BKS = minimum number of blocks to 

contain one record. 



3.3.4 Comments 

• If Allocation XABs are linked to the FAB, the create and extend op- 
erations ignore the FAB BKS field and obtain bucket size(s) from 
the XAB(s); see Chapters 5 and 8. 

• See the RMS-11 User's Guide for a discussion on bucket sizes. 

• Records may not span bucket boundaries. 
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************* 

* * 

* BLN * 

* * 
************* 



3.4 BLN 

The FAB$B macro sets the one-byte Block Length (BLN) field to the File 
Access Block length, with the symbolic value of FB$BLN. 

CAUTION 
DO NOT CHANGE THE BLN FIELD. 



3.4.1 Use 

Before RMS-11 uses a FAB during a file operation, it verifies that the 

block is a valid FAB; one of the checks examines the BLN field. If 

this field does not contain the proper code, RMS-11 aborts the opera- 
tion with a ER$BLN error code. 
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************* 

* * 

FILE ATTRIBUTE * BLS * 

* * 

************* 



3.5 BLS 

The one-word Block Size (BLS) field contains the physical block size' 
in characters for a Sequential file stored on MAGNETIC TAPE only. 



3.5.1 Use 

Input to: 

$CREATE 

You set the BLS field equal to the number of characters per 
physical block in the magtape file to be created. RMS-11 
rounds this number up to the next multiple of four before it 
creates the file and sets up an I/O buffer. 

Output from: 

$OPEN 

RMS-11 sets the BLS field equal to the size of the physical 
blocks in the "file existing on magtape. RMS-11 obtains the 
information from the file label on tape. If the information 
is not in the label, RMS-11 uses the default block size of 
the device. 



3.5.2 Input Values 

If you intend to use magtape to transfer data to a non-PDP-11 computer 
system, note the following: 

• If the destination is another DIGITAL system, block size should be 
less than or equal to 512 characters. 

• If the destination is a non-DIGITAL system, block size should be 
less, than or equal to 2048 characters. 



*A block on magnetic tape is the data between interblock gaps. block 
size is expressed in characters; the representation of a character 
on tape is determined by the tape formatting standard. 
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MINIMUM = 0, at run-time RMS-11 interprets a value of as the oper- 
ating system default: in all systems covered by this 
manual, the default is 512 characters. 

= 18, the smallest valid block size allowed by magtape device 
driver software 

MAXIMUM = 8192 characters 

A value can be set in the field with the initialization macro shown below 
or with the $STORE field access macro (see Chapter 7). 



3.5.3 Initialization and Default 
Macro takes the form: 

F$BLS numeric 
If there is no initialization macro, BLS = 0. 
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************* 

* * 

* BPA * 

* * 
************* 



3.6 BPA 

The one-word Buffer Pool Address (BPA) field points to an area in your 
program set aside for use as an I/O buffer for all Record Access Stre- 
ams connected to the file represented by the FAB. If the address is 
zero, you are allocating the I/O buffer in some other way (see 
Chapters 1 and 2) . 



3.6.1 Use 

Input to: 

$CREATE/$OPEN 

• If you want to specify a private buffer for the current 
file access (open to close), store the buffer's address 
in the BPA field before you open the file; also store 
the size of the buffer in the BPS field. 

• If you are not using a private buffer, ensure that the 
BPA field is zero; otherwise, RMS-11 interprets the 
value in the field as an address and tries to use the 
buffer indicated: the results are unpredictable. 

Output from: 

$CLOSE 

RMS-11 sets the BPA field equal to the address of the 
private buffer pool it is returning for your use. 



3.6.2 Input Values 

BPA must contain either: 

• zero (0) = there is no private buffer for this file; all space is 
allocated by RMS-11 from the central pool or by your GSA routine 

• address of the first byte of a private buffer for the file; the 
buffer must begin on a word boundary 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 
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3.6.3 Initialization and Default 
Macro takes the form: 

F$BPA label 
If there is no initialization macro, BPA = 0. 

3.6.4 Comments 

• If you are using a private buffer for the file's I/O buffer, you 
still have to allocate space in the central buffer pool for the 
internal structures (BDBs, IFAB, and so on) associated with the 
file; see Chapter 2. 

• Once you have assigned a private buffer to a file in a FAB and 
opened that file, you cannot use that space until the file is 
closed . 
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************* 

* * 

* BPS * 

* * 
************* 



3.7 B PS 

The one-word Buffer Pool Size (BPS) field contains the size, in bytes, 
of the private buffer indicated by the BPA field. RMS-11 uses this 
value to calculate the ending address of the private buffer. 

CAUTION 

RMS-11 does no further checking of the memory area defined 
by the FAB BPA and BPS fields. RMS-11 uses all the space 
allotted if it needs it. 



3.7.1 Use 



Input to: 

$CREATE/$OPEN 

If BPA is equal to zero, RMS-11 ignores the BPS field; if 
BPA is not equal to zero, that is, you are providing a pri- 
vate buffer, you must set the BPS field equal to size of 
that buffer in bytes. 

Output from: 

$CLOSE 

RMS-11 sets the BPS field equal to the size of the private 
buffer it is returning for your use. 



3.7.2 Input Values 

BPS must contain either: 

• any value* if the BPA field is zero 

• size of the private buffer for the file, in bytes, as a multiple of 
two 

To calculate the size of the private buffer, use the equation: 
BPS = strmszl + strmsz2 + ... + strmszn 



♦Recommended value is the default, zero. 
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where BPS is the size of the private buffer, 

strmszl are the I/O buffer space requirements (in bytes) for 
strmsz2 the Record Access Streams associated with the file that 
are active simultaneously. You calculate the require- 
strmszn ments for each stream as follows: 

— For Sequential files on disk: strmsz = 512*MBC 

— For Sequential files on magnetic tape: strmsz = BLS 

where BLS is the size, in characters, of each physi- 
cal block of the magtape file, that is, 
the value contained in the BLS field of 
the FAB, and 

MBC is the value contained in the MBC field of 
the RAB associated with the stream. 

— For Relative files: strmsz = BKS*512 

where BKS is the number of blocks in a bucket of the 
file (from the FAB BKS fields). 

— For Indexed files: strmsz = BKS*MBF*512 

where BKS is the number of blocks in the largest 
bucket of the file (selected from the FAB 
BKS and the Allocation XAB BKZ fields) , 
and 

MBF is the value contained in the MBF field of 
the RAB associated with the stream. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7>,. 



3.7.3 Initialization and Default 
Macro takes the form: 

F$BPS numeric 
If there is no initialization macro, BPS 



= 



0% 
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3.7.4 Examples 



.EVEN 
INBUF: .BLKB 4096. 



MASTER: FAB$B 



F$BPA INBUF 
F$BPS 4096 



FAB$E 
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************* 

* * 

* CTX * 

* * 
************* 



3.8 CTX 

The one-word User Context (CTX) field is not used by RMS-11, but is 
made available to you to contain any information you want associated 
with the file during run time. 



3.8.1 Use 

Anything you want. For example, you might use the CTX field to com- 
municate with a common completion routine. 



3.8.2 Input Values 

Anything you want, as long as it fits in 16 bits. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



3.8.3 Initialization and Default 
Macro takes the form: 

F$CTX argument 
where argument is any value you want. 
If there is no initialization macro, CTX 



= 0. 
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************* 

* * 

FILE ATTRIBUTE * DEQ * 

* * 

************* 



3.9 DEQ 

The one-word Default Extension Quantity (DEQ) field contains the 
number of blocks RMS-11 requests whenever it automatically extends the 
file (opposed to the explicit extend operation). RMS-11 requests ad- 
ditional blocks from the operating system* whenever a task attempts a 
put or update operation and there is not enough room in the file re- 
presented by the FAB to complete the operation. For Relative and In- 
dexed files, RMS-11 rounds DEQ up to the nearest multiple of bucket 
size before requesting the extension. 



3.9.1 Use 

Input to: 

$CREATE 

You set the DEQ field equal to the number of blocks that 
should be requested in each automatic extension of the file 
to be created. 

$OPEN 

You set the DEQ field equal to the number of blocks to be 
used by RMS-11 as a temporary default extension quantity 
until the file is closed; the file attribute is not 
changed. 

Output from; 

$OPEN 

If the DEQ field is zero, RMS-11 sets it equal to the number 
of blocks established as the default extension quantity when 
the file was created. 



3.9. 2 Input Values 

Default extension quantity should be a multiple of bucket size for Re- 
lative and Indexed files. 

MINIMUM = 0, meaning that whenever RMS-11 has to extend the file, it 
requests five blocks for Sequential files and four times 



♦Automatic extension can fail; see "Comments. 
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bucket size for Relative and Indexed files. 

MAXIMUM = 65,535 blocks 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 

3.9.3 Initialization and Default 
Macro takes the form: 

F$DEQ numeric 
If there is no initialization macro, DEQ = 0. 

3.9.4 Comments 

• If Allocation XABs are linked to the FAB, RMS-11 uses the FAB DEQ 
value as a file default extension quantity, substituting it whe- 
never an area has to be extended automatically and the XAB DEQ 
field for that area is zero. 

• Automatic extension can fail for at least the following reasons; 
there might be others: 

— Operating system is RSTS/E and file is: 

contiguous; error code = ER$PRV 
shared; error code = ER$PRV 

— No more room is available on the storage device; error code = 
ER$FUL 

• On the RSTS/E operating system, file allocation is done in 
clusters; see the RMS-11 User's Guide for a discussion of the in- 
teraction between clusters and default extension quantity. 

• See the RMS-11 User's Guide for a discussion of default extension 
quantity and its optimization. 
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************* 

* * 

* DEV * 

* * 

************* 



3.10 DEV 

The one-byte Device Characteristics (DEV) field contains a bit string 
indicating the generic characteristics of the device containing the 
file represented by the FAB. 



3.10.1 Use 

Output from: 

$CREATE/$OPEN 

RMS-11 sets the field equal to the appropriate device indi- 
cator. You can use field access macros (see Chapter 7) to 
examine the field. 



3.10.2 Output Values 

The DEV field contains one or more of the following symbolic values: 

FB$CCL Carriage control device, such as printer or terminal 

FB$MDI Multiple-directory-structured device, such as a disk with 
a Master File Directory and at least one User File Direc- 
tory 

FB$REC Unit record device, such as a terminal or line printer; 
all unit record devices are considered to be Sequential 
in nature 

FB$SDI Single-directory device, such as a disk with a Master 
File Directory, but no User File Directories present 

FB$SQD Sequential, block-oriented device, that is, magnetic tape 

FB$TRM Terminal device with keyboard and hard- or soft-copy out- 
put 



File Access Block (FAB): DEV 3-19 



************* 

* * 

* DNA * 

* * 
************* 



3.11 DNA 

The one-word Default Name String (DNA) field points to an ASCII string 
containing the program-specific defaults for file specifications. 
During the file open process, if the file name string indicated by the 
FNA field is not a complete file specification, RMS-11 examines the 
DNA field. If it is not zero, RMS-11 uses the string indicated to 
supply the missing components. If DNA is zero, or not all the de- 
faults are supplied by the DNA string, RMS-11 uses the system de- 
faults. 



3.11.1 Use 



Input to : 

$CREATE/$OPEN 



If you want to specify a default name string for a file 

operation, store the string's address in the DNA field 

before you initiate the operation; also store the size 
of the string in the DNS field. 

If you are not using a default name string, ensure that 
the DNA field is zero; otherwise, RMS-11 interprets the 
value in the field as an address and tries to use the 
string indicated: the results are unpredictable. 



3.11.2 Input Values 

The DNA field must contain either: 

• zero (0) = there is no default name string 

• address of the default name string. This string may contain values 
for one or more of the following file specification components: 

device 
account 
file name 
file type 
file extension 
version number 
protection code 
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DNA 



The string must be written in ASCII notation, that is, with the 
. ASCII/. ASCIZ MACRO-11 directive. 

A value can be set in the field with the initialization macro shown 
below or with the $SET field access macro (see Chapter 7). 



3.11.3 Initialization and Default 
Macro takes the form: 

F$DNA label 
If there is no initialization macro, DNA = 0. 

3.11.4 Examples 

To set up a default device specification: 

ANYFAB: FAB$B 

F$DNA DEFDEV 
F$DNS 3 

FAB$E 
DEFDEV: .ASCII /SY:/ 

3.11.5 Comments 

• The default name string may include logical names. 

• RMS-11 checks the DNA string validity during each create and open 
operation. RMS-11 returns an error if it finds a bad component 
even if the FNA string supplies a valid value for that component. 

• See also FNA discussion about file specifications, parsing sequence 
on RSTS/E, and so on. 
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************* 

* * 

* DNS * 

* * 
************* 



3.12 DNS 

The one-byte Default Name String Size (DNS) field contains the size, 
in bytes, of the default name string indicated by the DNA field. 



3.12.1 Use 

Input to: 

$CREATE/$OPEN 

If the DNA field is zero, RMS-11 ignores the DNA field; if 
the DNA field is not zero, that is, you are providing a de- 
fault name string, you must set the DNS field equal to the 
size of that string in bytes. 



3.12.2 Input Values j^ 
The DNS field must contain either: 

• any value*, if the DNA field is zero 

• the size of the default name string, in bytes, with a maximum of 
255 

A value can be set in the field with the initialization macro shown 

below or with the $STORE field access macro (see Chapter 7). ^^ 

3.12.3 Initialization and Default 
Macro takes the form: 

F$DNS numeric 
If there is no initialization macro, DNS = 0. 



♦Recommended value is the default, zero, 
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************* 

* * 

* FAC * 

* * 
************* 



3.13 FAC 

The one-byte File Access (FAC) field contains a bit string indicating 
the types of record operations that may be performed on the file re- 
presented by the FAB. This declaration enables RMS-11 to set up 
transfer vectors to the appropriate RMS-11 routines. RMS-11 rejects 
any record operation that was not specified in the FAC field when the 
file is opened (error code ER$FAC) . 



3.13.1 Use 

Input to : 

$CREATE 

You set the FAC field to indicate all operations your pro- 
gram performs on the file during the current access (open to 
close) . 

NOTE 
The FAC field must contain at least FB$PUT. 



$OPEN 

You set the FAC field to indicate all operations your pro- 
gram performs on the existing file during the current access 
(open to close) . 



3.13.2 Input Values 

FAC may contain one or more of the following symbolic values: 

FB$DEL $DELETE operations 

FB$GET $GET and/or $FIND operations 

FB$PUT $PUT operations 

FB$REA $READ Block I/O operations (see Chapter 9) 

FB$TRN $TRUNCATE operations: valid for Sequential files only 
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FB$UPD $UPDATE operations 

FB$WRT $WRITE Block I/O operations (see Chapter 9) 

If you want to specify more than one operation, you must concatenate 
the values using an exclamation point (!). 

A value can be set in the field with the initialization macro shown 
below or with the $SET field access macro (see Chapter 7). 



3.13.3 Initialization and Default 
Macro takes the form: 

F$FAC symbolic [! symbol ic. .. ] 
If there is no initialization macro, FAC = FB$GET. 

3.13.4 Comments 

• If the file is an ANSI magtape file, RMS-11 automatically positions 
the tape at the end of the file when it is opened, unless the FOP 
field contains FB$NEF. 

• Since the FAC field is a bit string, values cannot be added to the 
field with the $STORE field access macro. You should use the $SET 
field access macro (see Chapter 7). However, you use the $STORE 
macro to (re) set all bits in the field. 

• If you specify FB$DEL, FB$TRN, and/or FB$UPD, but do not include 
FB$GET, RMS-11 activates that capability anyway. Delete, truncate, 
and update operations must be preceded by a successful find or get 
operation. 
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************* 

* * 

* FNA * 

* * 
************* 



3.14 FNA 

The one-word File Name String Address (FNA) field points to the ASCII 
string that is the file specification of the file represented by the 
FAB. RMS-11 examines the string indicated, if FNA is not zero. If 
any file specification components are missing from the string, or FNA 
is zero, RMS-11 checks the DNA field. If DNA is not zero, RMS-11 uses 
the string indicated to fill in the filespec; if DNA is zero, or the 
string indicated is not sufficient, RMS-11 inserts system default va- 
lues into the file specification. Then it passes the complete files- 
pec to the operating system to either open or create, then open, a 
file by that name. 



3.14.1 Use 

Input to: 

$CREATE/$OPEN 

• If you want to specify a file specification for a file 
operation, store the specification's address in the FNA 
field before you initiate the operation; also store the 
size of the specification in the FNS field. 

• If you are not using a file specification*, ensure that 
the FNA field is zero; otherwise, RMS-11 interprets the 
value in the field as an address and tries to use the 
string indicated: the results are unpredictable. 



3.14.2 Input Values 
FNA must contain either: 

• zero (0) = there is no file specification 

• address of file specification string for the file 

The string must be written in ASCII notation, that is, with the 
. ASCII/. ASCIZ MACRO-11 directive. 



*If you are using all defaults, program and/or system, to define the 

file specification, or file ID to identify the file without a file 
specification (see Chapter 8). 
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A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



3.14.3 Initialization and Default 
Macro takes the form: 

F$FNA label 
If there is no initialization macro, FNA = 0. 

3.14.4 Comments 

• File specifications contained in the FNA-indicated buffer must con- 
form to operating system standards. See the RMS-11 User's Guide, 
Appendix A, for RMS-11 restrictions on the operating systems and 
operating system restrictions on RMS-11. 

• On RSTS/E, RMS-11 parses file specifications in the following se- 
quence. RMS-11: 

1. Places the string described by the DNA and DNS fields in the 
FIRQB. 

2. Issues a .FSS call on the string described by the FNA and FNS 
fields. In the process, the monitor merges the FNA and DNA 
strings in the FIRQB, overriding only those components already 
existing in the FNA string. The monitor also translates logi- 
cal names. 

3. Checks if the FSS processing encountered an RMS-11 restriction 
on RSTS/E file specifications, such as switches or an equal 
sign ( = ) . 

4. Examines the resultant file specification for device and ac- 
count components. If these components are missing, RMS-11 ob- 
tains the system defaults for those fields and puts them into 
the file specification. 

5. Examines the resultant file specification. If a component is 
missing, returns the appropriate error code; if there are too 
many components, returns the error code ER$XTR. 
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************* 

* * 

* FNS * 

* * 
************* 



3.15 FNS 

The one-byte File Name String Size (FNS) field contains the size, in 
bytes, of the file specification indicated by the FNA field. 



3.15.1 Use 

Input to: 

$CREATE/$OPEN 

If the FNA field is zero, RMS-11 ignores the FNA field; if 
FNA is not zero, that is, you are providing a file specifi- 
cation, you should set the FNA field equal to the size of 
that string in bytes. 



3.15.2 Input Values 

The FNA field must contain either: 

• any value* if FNA is zero 

• size of the file specification string, in bytes, with a maximum of 
255 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



3.15.3 Initialization and Default 
Macro takes the form: 

F$FNS numeric: 
If there is no initialization macro, FNS = 0. 



♦Recommended value is the default, zero. 



File Access Block (FAB): FNS 3-27 



************* 

* * 

* FOP * 

* * 
************* 
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3.16 FOP 

The one-word File Processing Options (FOP) field contains a bit string 
indicating the file processing options that you have selected for the 
file represented by the FAB. 



3.16.1 Use 

Input to: ^gj^ 

$CREATE 

You set the FOP field to indicate the processing option(s) 
you want applied to the new file until it is closed. 

$OPEN 

You set the FOP field to indicate the processing options you 
want applied to the existing file until it is closed. 

$EXTEND iffl 

You set the FOP field equal to FB$CTG if you want the file 
extended contiguously, that is, the new blocks allocated in 
such a manner that they are contiguous with the present ex- 
tent of the file. 

$CLOSE 

You set the FOP field equal to FB$RWC if you want a magnetic 
tape file rewound when the file is closed, but did not in- 
clude the option when the file was opened. jm^ 

Output from: 

$OPEN 

If the file is contiguous, RMS-11 sets the FOP field equal 
to FB$CTG; otherwise, the field is zero. You can test for 
this value with field access macros (see Chapter 7). 



3.16.2 Input Values 

The FOP field may contain one or more of the following symbolic 
values: 

FB$CTG RMS-11 is to allocate contiguously the amount of space ^-^ 
specified in the FAB ALQ field. Used on $CREATE and "I 
$EXTEND only. 
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FB$DFW directs RMS-11 to defer writing the I/O buffer out to a 
file after a $DELETE, $UPDATE, or $PUT operation. Under 
default conditions, RMS-11 causes a physical transfer of 
data from your program to the file as part of any of the 
above record operations — for Relative and Indexed files 
only. However, if you specify FB$DFW in the RAB when you 
initiate one of these operations, RMS-11 does not auto- 
matically write out the buffer. Instead, it defers the 
disk write until it requires the buffer for some other 
purpose, such as reading a different bucket into memory 
or the buffer is full. Since this is similar to the de- 
fault condition for Sequential files, specifying Deferred 
Write does not affect record operations on Sequential 
files. 

FB$DLK RMS-11 unlocks the file so that it is available for ac- 
cess if this program does not close it in a normal 
manner. Used on " $CREATE and $OPEN only. See 
"Comments." 

FB$FID RMS-11 uses the value in the NAM FID field to open or 
erase the file (see Chapter 8). Used on $OPEN and $ERASE 
only. 

FB$MKD RMS-11 creates this file, then deletes it when the file 
is closed. Used on $CREATE only. 

FB$NEF RMS-11 does not position the ANSI magnetic tape to the 
end of the file even though the FAB FAC field contains 
FB$PUT. Used on $OPEN only. 

FB$POS RMS-11 positions the magtape to the point immediately 
after the most recently closed file before it creates the 
file specified by this FAB; all subsequent files on the 
tape are logically deleted. If FB$POS is not specified, 
RMS-11 positions the magtape at the end of the last file 
on the volume. However, the FB$RWO option overrides the 
FB$POS option. Used on $CREATE only. 

FB$RWC RMS-11 requests the operating system to rewind the mag- 
tape when the file is closed. If FB$RWC is set when the 
file is opened ($CREATE or $OPEN) , RMS-11 does not notice 
its absence when the file is closed; that is, you can't 
undo this once specified. However, if FB$RWC was not 
specified for the open, you can include it for the $CLOSE 
and RMS-11 rewinds the tape. 

FB$RWO RMS-11 requests the operating system to rewind the mag- 
tape before the file represented by the FAB is created 
and/or opened. Used on $CREATE and $OPEN only. 

FB$SUP RMS-11 supersedes an existing file if the file specifi- 
cation indicated by this FAB contains an explicit version 
number. Used on $CREATE only. 
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FB$TMD RMS-11 creates this file as a temporary file and deletes 
it when the file is closed. Used on $CREATE only. 

FB$TMP RMS-11 creates this file as a temporary file and does not 
delete it; that is, RMS-11 retains the file, when it is 
closed, even though it is not entered into the directory. 
The FB$TMD option overrides the FB$TMP option. Used on 
$CREATE only. 

If you want to specify more than one option, you must concatenate the 
values using an exclamation point (!). 

A value can be set in the field with the initialization macro shown 
below or with the $SET field access macro (see Chapter 7). 

3.16.3 Initialization and Default 
Macro takes the form: 

F$FOP symbol ic [! symbol ic. .] 
If there is no initialization macro, FOP = 0, meaning: 

• The file is created or extended noncontiguously. 

• If file is not closed normally, it remains locked (see "Comments"). 

• Open operation accesses file via filespec. 

• RMS-11 positions magtape to end of the file when it opens the file. 

• RMS-11 positions magtape to end of the last file on volume before 
it creates the specified file. 

• RMS-11 does not request the operating system to rewind magtape when 
the file is closed. 

• RMS-11 fails with error code ER$FEX if the filespec contains an 
explicit version number and the file already exists. 

• RMS-11 creates a permanent file. 

3.16.4 Comments 

• The IAS and RSX-11M operating systems provide protection to any 
file that is not closed properly* by a task that creates or opens 
it: the file is locked and not accessible by any user task until a 
utility (PIP) unlocks it. 

This protection is particularly valuable for Sequential files. 
When RMS-11 opens a Sequential file, it reads the file's attri- 
butes, including end-of-file location from the file header into 
memory; however, RMS-11 does not update the file header until the 
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file is closed. Until the file's attributes are revised on disk, 
any extension of the file while it was opened (and any data added 
to it) is not permanently recorded. Therefore, if a Sequential 
file is not closed properly*, all data added while it was open 
could be lost if another task does access the file and make its own 
revision of the file header. 

These considerations do not apply to Relative and Indexed files. 
Therefore, they are the only files for which the FB$DLK value 
should be specified. 

Since the FOP field is a bit string, values cannot be added to the 
field with the $STORE field access macro. You should use the $SET 
field access macro (see Chapter 7). However, you use the $STORE 
macro to (re) set all bits in the field. 



*Caused by an improperly designed task, operating system collapse, or 
hardware malfunction. 
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************* 

* * 

FILE ATTRIBUTE * FSZ * 

* * 
************* 



3.17 FSZ 

The one-byte Fixed Control Area Size (FSZ) field contains the size, in 
bytes, of the fixed control area for Variable-with-Fixed-Control (VFC) 
records in the file represented by the FAB. 



3.17.1 Use 

The FSZ field is only used when a file contains (or will contain) VFC 
records. It therefore applies only to Sequential and Relative files. 

Input to: 

$CREATE 

You set the FSZ field equal to the number of bytes in the 
fixed control area of the VFC records that will be written 
into the file to be created. 

Output from: 

$OPEN 

RMS-11 sets the FSZ field to the size of the fixed control 
area established when the file was created. 



3.17.2 Input Values 

MINIMUM = 0, meaning that RMS-11 sets the control area size to two 
bytes* 

= 1, the smallest fixed control area allowed 

MAXIMUM =255 

A value can be set in the field with the initialization macro shown 
below or with the $ST0RE field access macro (see Chapter 7). 



3.17.3 Initialization and Default 
Macro takes the form: 

F$FSZ numeric 
♦Compatible with FCS. 
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If there is no initialization macro, FSZ = 0. 



3.17.4 Comments 

RMS-11 uses this number as the size of the buffer indicated by the RAB 
RHB field. 
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************* 

* * 

* I FI * 

* * 

************* 



3.18 IFI 

The $OPEN macro sets the one-word Internal File Identifier (IFI) field 
to an address that links the FAB to the IFAB RMS-11 creates when a 
file is opened. The $CLOSE macro clears the IFI field. 

CAUTION 
DO NOT CHANGE THE IFI FIELD. 



3.18.1 Use 

RMS-11 uses the address in the IFI field to transfer pertinent data 
from the FAB to the IFAB. 
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************* 

* * 

* LCH * 

* * 

************* 



3.19 LCH 

The one-byte Logical Channel (LCH) field contains the number of the 
logical channel through which all I/O operations between the file and 
the task are performed. 



3.19.1 Use 

Input to: 

$CREATE/$OPEN 

You set the LCH field to the number of the channel the file 
should be linked with until it is closed. Each file opened 
must have a unique LCH (error code ER$LBY) . 



3.19.2 Input Values 

MINIMUM is system-dependent 

MAXIMUM is system-dependent 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 

3.19.3 Initialization and Default 
Macro takes the form: 

F$LCH numeric 

If there is no initialization macro, LCH = 0, meaning the field must 

be set with the $ST0RE 
field access macro be- 
fore the file open is 
attempted . 
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3.19.4 Comments 

• Multiple Record Access Streams is a method of using one logical 
channel to carry multiple functions. 

• Once a logical channel is assigned to a device, no operation, in- 
cluding $CLOSE, automatically deassigns the channel. The channel 
remains assigned to the device until you reassign it. 
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************* 

* * 

FILE ATTRIBUTE * MRN * 

* * 

************* 



3.20 MRN 

The two-word Maximum Record Number (MRN) field contains the maximum 
number of records that can be written to the Relative file associated 
with the FAB. RMS-11 checks the relative record number used with each 
put operation against this maximum and rejects (error code ER$MRN) any 
operation with too high a number. 



3.20.1 Use 

The MRN field is only meaningful for Relative files. 

Input to i 

$CREATE 

You set the MRN field to the highest relative number of any 
record that will (or should) be written into the file*. If 
you want no checks on relative record number, set MRN equal 
to zero. 

Output from: 

$OPEN 

RMS-11 sets the MRN field equal to the value established 
when the file* was created. 



3.20.2 Input Values 

MINIMUM = 0, meaning that RMS-11 writes the MRN value as 

2,147,483,647** during the create operation, returns 
this number during an open operation, and makes no 
checks on relative record numbers during put opera- 
tions. 

MAXIMUM = number of records that will fit on the device containing 
the file 



*Unless the FAB ORG field contains FB$REL, RMS-11 ignores the MRN 

field during $CREATE and sets it to zero during $OPEN. 
**The largest possible positive value for the 32-bit field. 
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A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



3.20.3 Initialization and Default 
Macro takes the form: 

F$MRN numeric 
If there is no initialization macro, MRN = 0. 
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************* 
* * 

FILE ATTRIBUTE * MRS * 

************* 



3.21 MRS 

The one-word Maximum Record Size (MRS) field contains the maximum 
size, in bytes, of any record in the file associated with the FAB. 
RMS-11 checks all records written to the file against this maximum and 
rejects those that are too large (error code ER$RSZ) . 



3. 21 . 1 Use 

Input tos 

$CREATE 

You set the MRS field equal to the number of bytes in: 

• all fixed-length records in the file 

• the largest variable-length or stream record that can be 
written to the file. 

• The variable area in the largest VFC record that can be 
written to the file, that is, the number does not include 
the fixed control area. 

Output from: 

$OPEN 

RMS-11 sets the MRS field equal to the value established 
when the file was created. 



3. 21.2 Input Values 

MINIMUM = 0, meaning that RMS-11 makes no checks on the length of re- 
cords written to the file via either $PUT or $UPDATE. 
However, there are restrictions on the use of zero in the 
MRS field; see "Comments." 

MAXIMUM = 32767, the largest number, that can be stored in the signed 

two-byte field. However, Maximum Record Size is 
further limited by bucket size in Relative and In- 
dexed files and by task buffer space for all files. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 
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3.21.3 Initialization and Default 
Macro takes the form: 

F$MRS numeric 
If there is no initialization macro, MRS = 0. 

3.21.4 Comments 

A nonzero MRS field is required during the $CREATE operation in the 
following situations: 

• Fixed-length records (FAB RFM field = RB$FIX) 

• Relative file organization (FAB ORG field = FB$REL) 
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************* 

* * 

* NAM * 

* * 
************* 



3.22 NAM 



The one-word Name Block Address (NAM) field points to a separately al- 
located Name Control Block (NAM) and thereby activates RMS-11 to use 
the NAM Block when the file is opened. See Chapter 6. 



3.22.1 Use 



Input to 



$CLOSE 

If you have specified a valid NAM Block, RMS-11 clears the 
first word of the FID field, making the field invalid for 
any subsequent operations. 



$CREATE 



$ERASE 



If you have allocated a NAM Block and want RMS-11 to set 
the fields when it opens the file, you set the NAM field 
equal to the address of the block. 

If you have not allocated a NAM Block and/or you do not 
want RMS-11 to fill it in during the file open procedure, 
set the NAM field equal to zero; otherwise, RMS-11 in- 
terprets the value in the field as an address and tries 
to use the area indicated as a NAM Block: if that area 
is not a valid NAM Block, RMS-11 returns the error code 
ER$NAM. 



If you want RMS-11 to use the device and file IDs in NAM 
DVI and FID fields to identify, then erase a file. The 
file ID must be valid and probably was supplied by RMS-11 
during a create or open operation. You must also set 
FB$FID in the FAB FOP field. 

If you have not allocated a NAM Block and/or you do not 
want RMS-11 to use it in during the erase operation, set 
the NAM field equal to zero; otherwise, RMS-11 inter- 
prets the value in the field as an address and tries to 
use the area indicated as a NAM Block: if that area is 
not a valid NAM Block, RMS-11 returns the error code 
ER$NAM. 



.jlP'^Wm 
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$OPEN 



If you have allocated a NAM Block and want RMS-11 to fill 
in the fields when it opens the file, you set the NAM 
field equal to the address of the block. 

If you want RMS-11 to use the device and file IDs in NAM 
DVI and FID fields to identify, then open a file. The 
file ID must be valid and probably was supplied by RMS-11 
during a create or open operation. You must also set 
FB$FID in the FAB FOP field. 

If you have not allocated a NAM Block and/or you do not 
want RMS-11 to fill it in during the open operation, set 
the NAM field equal to zero; otherwise, RMS-11 inter- 
prets the value in the field as an address and tries to 
use the area indicated as a NAM Block: if that area is 
not a valid NAM Block, RMS-11 returns the error code 
ER$NAM. 



3.22.2 Input Values 

The NAM field must contain either: 

• zero (0) = there is no NAM Block associated with this FAB 

• address of a Name Control Block separately allocated in the program 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 

3.22.3 Initialization and Default 
Macro takes the form: 

F$NAM label 
If there is no initialization macro, NAM = 0. 
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************* 

* * 

FILE ATTRIBUTE * ORG * 

* * 
************* 



3.23 ORG 

The one-byte File Organization (ORG) field contains an indicator for 
the organization of the file associated with the FAB. 



3.23.1 Use 



Input to: 

$CREATE 

You set the ORG field to indicate the organization you want 
established for the file to be created. 

Output from: 

$OPEN 

RMS-11 stores in the ORG field the indicator for the organi- 
zation of the existing file. You can test this value with 
field access macros (see Chapter 7). 



3.23.2 Input Values 

The ORG field may contain one of the following symbolic values: 

FB$SEQ Sequential file organization 

FB$REL Relative file organization 

FB$IDX Indexed file organization 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 

3.23.3 Initialization and Default 
Macro takes the form: 

F$ORG symbolic 
If there is no initialization macro, ORG = FB$SEQ. 
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************* 

* * 

FILE ATTRIBUTE * RAT * 

* * 
************* 



3.24 RAT 



The one-byte Record Attributes (RAT) field contains a bit string des- 
cribing the attributes of the records in the file associated with the 



FAB. 



3.24.1 Use 



Input to: 



$CREATE . , , 

You set the RAT field to indicate the characteristics of the 
records that will be stored in the file to be created. 



Output from: 
$OPEN 



RMS-11 stores in the RAT field indicators of the record at- 
tributes established for the file when it was created. You 
can test for these values using field access macros (see 
Chapter 7) . 



3.24.2 Input Values 

The RAT field may contain one or more of the following symbolic 
values: 

FB$BLK records in the file do not cross block boundaries; valid 
only for Sequential files. This attribute restricts re- 
cord size to 512 bytes. 

FB$CR when RMS-11 writes a record from this file to a unit re- 
cord device, that is, a terminal or printer opened as a 
Sequential file, it precedes the record with a line feed 
character and follows it with a carriage return char- 
acter. RMS-11 may or may not actually add the char- 
acters, depending on the operating system. 

FB$FTN the first byte of each record in the file contains a FOR- 
TRAN forms control character 

If you want to specify more than one attribute, you must concatenate 
the values using an exclamation point (!). 
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A value can be set in the field with the initialization macro shown 
below or with the $SET field access macro (see Chapter 7). 



3.24.3 Initialization and Default 
Macro takes the form: 

F$RAT symbolic [! symbol ic. .. ] 
If there is no initialization macro, RAT = 0, meaning: 

• Records span block boundaries 

• No carriage or FORTRAN control 

3.24.4 Comments 

• If the file associated with the FAB is a unit record device, such 
as a terminal or printer, you should put at least FB$CR in the RAT 
field. 

• By default, records in all files are allowed to cross block boun- 
daries. Although this attribute can be restricted for Sequential 
files, there seems to be little reason to do so. 

• Since the RAT field is a bit string, values cannot be added to the 
field with the $STORE field access macro. You should use the $SET 
field access macro (see Chapter 7). However, you use the $STORE 
macro to (re) set all bits in the field. 
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************* 

* * 

FILE ATTRIBUTE * RFM * 

* * 

************* 



3.25 RFM 



The one-byte Record Format (RFM) field contains an indicator for the 
format of the records in the file associated with the FAB. 



3.25.1 Use 



Input to: 



$CREATE 

You set the RFM field to indicate the record format you want 
established for the file to be created. 



Output from: 
$OPEN 



RMS-11 stores in the RFM field the indicator for the record 
format of the existing file. You can test this value with 
field access macros (see Chapter 7). 



3.25.2 Input Values 

The RFM field may contain one of the following symbolic values: 

FB$FIX fixed-length records 

FB$STM ASCII stream record format; valid only for disk Sequen- 
tial files. The RMS-11 User's Guide explains how RMS-11 
handles stream records. 

FB$UDF no record format is defined for the file; valid only for 
Sequential files during create operations. When access- 
ing a file with undefined record format, your program 
must use block I/O (see Chapter 9). 

FB$VAR variable-length records 

FB$VFC variable-with-fixed-control records; valid only for disk 
Sequential and Relative files 



A value can be set in the field with the initialization macro sh 
below or with the $STORE field access macro (see Chapter 7). 



own 
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3.25.3 Initialization and Default 
Macro takes the form: 

F$RFM symbolic 
If there is no initialization macro, RFM = FB$VAR. 
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************* 

* * 

* RTV * 

* * 
************* 



The meaning of the RTV field depends on your operating system. This 
section defines the field for: 

IAS/RSX-11M 



3.26 RTV 

The one-byte Retrieval Window Size (RTV) field contains the number of 
retrieval pointers kept in memory* for the file represented by the 
FAB. Retrieval pointers map virtual block numbers to logical block 
numbers. See Chapter 8 of the RMS-11 User's Guide for more informa- 
tion. 



3.26.1 Use 

Input to : 

$CREATE/$OPEN 

You set the RTV field equal to the size of window you want 
maintained for the file until it is closed. 



3.26.2 Input Values 

The RTV field must contain one of the following: 

• -1 = as much of the file as possible is mapped with one window 

• = RMS-11 uses the current default value 

• a nonzero positive value, specifying the number of retrieval po- 
inters to be maintained in memory: 

MINIMUM = 1 
MAXIMUM = 127 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



*This set of pointers is called a "window." 
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3.26.3 Initialization and Default 
Macro takes the form: 

F$RTV numeric 
If there is no initialization macro, RTV = 
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************* 

* * 

FILE ATTRIBUTE * RTV * 

* * 

************* 



The meaning of the RTV field depends on your operating system. This 
section defines the field for: 

RSTS/E 



3.27 RTV 

The one-byte Clustersize (RTV) field contains the number of blocks in 
each cluster of the file represented by the FAB. 



3.27.1 Use 

Input to: 

$CREATE 

You set the RTV field to the clustersize you want esta- 
blished for the file to be created. 

Output from: 

SOPEN 

RMS-11 sets the RTV field to the clustersize established for 
the file when it was created. 



3.27.2 Input Values 

The value in the RTV field must be: 

• a positive integer 

• a power of two; else ER$CRE 

• greater than or equal to volume* clustersize 

MINIMUM = 0, meaning that RMS-11 uses the volume* clustersize 

MAXIMUM = 255, meaning that RMS-11 sets clustersize to 256 blocks 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



♦"Volume" means the disk pack as opposed to the disk device, which has 
its own characteristic clustersize. 



File Access Block (FAB): RTV 3-49 



3.27.3 Initialization and Default 
Macro takes the form: 

F$RTV numeric 
If there is no initialization macro, RTV 



= 0, 



■d^^^^N^ 
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************* 

* * 

* SHR * 

* * 
************* 



3.28 SHR 

The one-byte File Sharing (SHR) field contains a bit string indicating 
the operations on the file represented by the FAB you are willing to 
share with other tasks. This sharing criterion is applied whether or 
not this is the first task to access the file: if one or more other 
tasks have already opened the file to write and the SHR field indi- 
cates no write sharing, the open operation fails; however, if this 
task is the first to open the file, specifying no write sharing, all 
other tasks that indicate write operations* are denied access. 

See also Chapter 2 of the RMS-11 User's Guide. 



3.28.1 Use 

Input to: 

$CREATE/$OPEN 

You set the SHR field to indicate the type of operations you 
allow other tasks accessing the file. 



3.28.2 Input Values 

The SHR field may contain one of the following: 

• zero (0), meaning no write sharing; however, other tasks may ac- 
cess the file for reading only (FB$GET only in the FAB ROP field) 

• FB$WRI, meaning that other tasks may access the file for write op- 
erations 



NOTE 

For Sequential files, FB$WRI can be used only when the FAC 
field does NOT contain FB$PUT or FB$UPD. If you want write 
access, you cannot allow others to have write access. 



A value can be set in the field with the initialization macro shown 
*FB$DEL, FB$PUT, and/or FB$UPD in FAB ROP field. 
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below or with the $SET field access macro (see Chapter 7). 



3.28.3 Initialization and Default 
Macro takes the form: 

F$SHR FB$WRI 
If there is no initialization macro, SHR 



= 0, 
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************* 

* * 

* 3ts * 

* * 
************* 



3.29 STS 

The one-word Completion Status Code (STS) field contains a code indi- 
cating the success or failure (and type of failure) of a file opera- 
tion. See Appendix A for symbolic and octal codes for both success 
and failure of operations. 



3.29.1 Use 

Output from: 

$CLOSE/$CREATE/$DISPLAY/$ERASE/$EXTEND/$OPEN 

RMS-11 sets the STS field equal to a completion code. You 
should test this field ($COMPARE field access macro) for a 
negative value after each file operation, or you can use an 
error completion routine that checks the value (see Chapter 
8) . 



3.29.2 Input Values 

No input values; see Appendix A for output values. 
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************* 

* * 

* STV * 

* * 

************* 



3.30 STV 

The one-word Status Value (STV) field contains additional information 
about some error codes returned in the STS field. 



3.30.1 Use 
Output from: 

$CLOSE/$CREATE/$DISPLAY/$ERASE/$EXTEND/$OPEN 

RMS-11 sets the STV field whenever it has additional infor- 
mation to communicate about an error. See Appendix A for 
the specific errors on which the STV field is used. You 
should check the STV field for a nonzero value whenever you 
detect an error (negative value in STS field) . 



3.30.2 Input Values 

No input values; see Appendix A for output values. 
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************* 

* * 

* XAB * 

* * 
************* 



3.31 XAB 

The one-word Extended Attribute Block Address (XAB) field, if not 
zero, points to a separately allocated Extended Attribute Block (XAB) 
and thereby indicates to RMS-11 that there is a chain of at least one 
XAB that must be examined for input to and filled with output from a 
file operation. RMS-11 finds the other XABs in the chain, if there 
are any, via the NXT field in the XAB indicated by the FAB XAB field. 



3.31.1 Use 
Input to: 

$CREATE/$DISPLAY/$EXTEND/$OPEN 

• If you have allocated one or more XABs and want RMS-11 to 
use the chain, you set the XAB field equal to the address 
of the first XAB in the chain. 

• If you have not allocated an XAB and/or you do not want 
RMS-11 to use it during the file open procedure, set the 
XAB field equal to zero; otherwise, RMS-11 interprets 
the value in the field as an address and tries to use the 
area indicated as an XAB: if that area is not a valid 
XAB, RMS-11 returns error code ER$XAB. 



3.31.2 Input Values 

The XAB field must contain either: 

• zero (0) = there is no XAB associated with this FAB 

• address of an Extended Attribute Block separately allocated in the 
program 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



3.31.3 Initialization and Default 
Macro takes the form: 
F$XAB label 
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If there is no initialization macro, XAB = 0. 

3.31.4 Comments 

• See Chapter 5 for details on XABs. 

• An Indexed file requires at least one XAB to define the Primary 
Key. 
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CHAPTER 4 
RECORD ACCESS BLOCK 



The initialization macros (this chapter) and the field access macros 
(Chapter 7) are provided so that you do not have to know the specific 
position and to a large extent, the size of each field in a RAB. You 
can, therefore, treat the fields as logical entities. It is also pos- 
sible that the positions and sizes of the fields will change from re- 
lease to release of RMS-11. 

However, you can determine the position of any field in a RAB as an 
offset from the RAB • s starting address. RMS-11 represents these off- 
set values with symbols in one of the following forms: 

• 0$fnm 

where fnm is the three-letter name of a one-byte or one-word field; 
fnm is the name used to reference the field in the initialization 
and field access macros. 

Example 0$STS for the status code field 

• 0$fnmx 

where fnm is the name of a multiword field; fnm is the name used 
to reference the field in the initialization and field 
access macros. 

x is a number associated with an individual word in the 
field, from through the end of the field. 

Example 0$BKTO for less significant word and Q$BKT1 for the more 
significant word in the BKT field 

The values of these symbols can be found in the symbol table of an as- 
sembly listing file for any module containing the RAB. 



Table 4-1: Record Access Block Fields 



Field 


Field 


Default 


Description 


Name 


Si ze 






BID 


IB 


N/A 


RAB identifier 


BKT 


2W 


None 


Relative record number or VBN 


BLN 


IB 


N/A 


RAB length 


CTX 


1W 





User area 


FAB 


1W 





FAB address 


ISI 


1W 


N/A 


Pointer to IRAB 


KBF 


1W 





Key buffer address 


KRF 


IB 





Key of reference 


KSZ 


IB 





Key buffer size 


MBC 


IB 





Multiblock count 


MBF 


IB 





Multibuffer count 


RAC 


IB 





Record Access Mode 


RBF 


1W 





Address of output record 


RFA 


3W 





Record's File Address 


RHB 


1W 





Fixed control area buffer 


ROP 


1W 





Record processing options 


RSZ 


1W 





Size of output record 


STS 


1W 


N/A 


Completion status code 


STV 


1W 


N/A 


Status value 


UBF 


1W 





Input record buffer 


USZ 


1W 





Input record buffer size 
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************* 

* * 

* BID * 

* * 
************* 



4.1 BID 

The RAB$B macro sets the one-byte Block Identifier (BID) field to the 
Record Access Block identifier, with the symbolic value of RB$BID. 

CAUTION 
DO NOT CHANGE THE BID FIELD. 



4.1.1 Use 



Before RMS-11 uses a RAB during a record operation, it verifies that 
the block is a valid RAB; one of the checks examines the BID field. 
If this field does not contain the proper code, RMS-11 terminates the 
operation with a ER$RAB error code. 
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************* 

* * 

* BKT * 

* * 
************* 



4.2 BKT 

The one-byte Bucket (BKT) field contains: 

• the relative record number of the record accessed by the Record Ac- 
cess Stream during sequential access operations on a Relative file 

• the Virtual Block Number when the Record Access Stream is perform- 
ing Block I/O operations 



4.2.1 Use 

Input to Block I/O Operations: 

$READ/$WRITE 

You set the BKT field equal to the number of the virtual 
block you want read or written. 

Output from Relative File record operations: 

$FIND/$GET/$PUT 

If you have specified sequential access (RB$SEQ in the RAB 
RAC field) , RMS-11 sets the BKT field equal to the relative 
record number of the record read or written by the opera- 
tion. 



4.2.2 Input Values (Block I/O only) 
MINIMUM = 

MAXIMUM = value of FAB ALQ field 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 

4.2.3 Initialization and Default 

Logical for Block I/O operations only, the macro takes the form: 

R$BKT numeric 
If there is no initialization macro, BKT = 0. 
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************* 

* * 

* BLN * 

* * 
************* 



4.3 B LN 

The RAB$B macro sets the one-byte Block Length (BLN) field to the Re- 
cord Access Block length, with one of the following symbolic values: 

RB$BLN = synchronous RAB 
RB$BLL = asynchronous RAB 

CAUTION 
DO NOT CHANGE THE BLN FIELD. 



4.3.1 Use 



Before RMS-11 uses a RAB during a record operation, it verifies that 
the blocks is a valid RAB; one of the checks examines the BLN field. 
If this field does not contain the proper code, RMS-11 aborts the op- 
eration with a ER$BLN error code. 
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************* 

* * 

* CTX * 

* * 
************* 



4.4 CTX 



The one-word User Context (CTX) field is not used by RMS-11, but is 
made available to you to contain any information you want associated 
with the Record Access Stream during run time. 



4.4.1 Use 

Anything you want. For example, you might use the CTX field to com- 
municate with a common completion routine. 



4.4.2 Input Values 

Anything you want, as long as it fits in 16 bits. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 

4.4.3 Initialization and Default 
Macro takes the form: 

R$CTX argument 
where argument is any value you want. 
If there is no initialization macro, CTX = 0. 
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************* 

* * 

* FAB * 

* * 
************* 



4 . 5 FAB 

The one-word File Access Block (FAB) field points to the File Access 
Block connected to this RAB to form a Record Access Stream (RAS) . The 
FAB must be associated with an open file at the time the $CONNECT 
macro is used. If an invalid address is stored in the FAB field, 
RMS-11 returns error code ER$IFI. 



4.5.1 Use 



Input to: 

SCONNECT 

You set the FAB field equal to the address of the FAB you 
want associated with this RAB to make a Record Access Stre- 
am. 



4.5.2 Input Values 

Before the $CONNECT macro is executed, you must put a valid FAB ad- 
dress in the FAB field. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



4.5.3 Initialization and Default 
Macro takes the form: 

R$FAB label 
If there is no initialization macro, FAB 



0, meaning you must set the 
field with the $STORE 
field access macro be- 
fore initiating 
$CONNECT. 
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4.5.4 Comments 

If you are using the same FAB for more than one file, you should set 
up all Record Access Streams associated with one file before you modi- 
fy the FAB in preparation for another $OPEN or $CREATE. 



;*^^"l®\ 
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************* 

* * 

* ISI * 

* * 

************* 



4.6 ISI 

The $CONNECT macro sets the one-word Internal Stream Identifier (ISI) 
field to an address that links the RAB to the IRAB RMS-11 has created. 

CAUTION 
DO NOT CHANGE THE ISI FIELD. 



4.6.1 Use 

RMS-11 uses the address in the ISI field to transfer pertinent data 
from the RAB to the IRAB. 
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************* 

* * 

* KBF * 

* * 
************* 



4.7 KBF 

The one-word Key Buffer (KBF) field points to the key that RMS-11 uses 
to locate a record during a random record operation: 

• For Relative files, RMS-11 uses the value as the relative record 
number for $FIND, $GET, and $PUT operations. 

• For Indexed files, RMS-11 uses the buffer contents as the key value 
during its index search for $FIND and $GET operations. The RAB KRF 
field determines the specific index searched and the contents of 
the RAB KSZ and ROP fields decide the match criteria used. 



4.7.1 Use 

Input to: 

$FIND/$GET 

You set the KBF field to the address of the buffer in your 
program that contains the key for the next random record op- 
eration (RB$KEY in RAB RAC field) . You must also set the 
KSZ and ROP fields appropriately. 

$PUT 

For Relative files, you set the KBF field to indicate the 
relative record number of the cell where RMS-11 should write 
the specified record. 



4.7.2 Input Values 

The KBF field must contain a valid address before any random record 
operation macro is executed. 

The address must indicate a buffer in the current program that con- 
tains either: 

• a relative record number as a two-word integer that is positive, at 
least 1, and no greater than the Maxium Record Number (MRN) set for 
the file when it was created. The address must point to the least 
significant byte of the record number. 

• a key value for an index search; this value can be any of the 
valid Indexed key types. 
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The buffer does not have to be word-aligned. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



4.7.3 Initialization and Default 

Macro takes the form: 

R$KBF label 

If there is no initialization macro, KBF = 0, meaning you must set the 

field with the $ST0RE 
field access macro be- 
fore any random record 
operation. 
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************* 

* * 

* KRF * 

* * 
************* 



4.8 KRF 

The one-byte Key of Reference (KRF) field indicates the index to be 
referenced in the current operation. 



4.8.1 Use 

The KRF field is only used for record operations on Indexed files. 

Input to: 

$FIND/$GET 

You set the KRF field to indicate the index that should be 
searched for the value defined by the contents of the KBF 
and KSZ fields; match criterion is also specified by the 
ROP field. 

$CONNECT/$REWIND 

You set the KRF field to indicate the index that is used to 
set the context of the Record Access Stream, that is, the 
logical first record in the file. 



4.8.2 Input Values 

MINIMUM = 0, meaning the Primary Key 

MAXIMUM == 254 

All values beginning with 1 indicate Alternate Keys, first, second, 
and so on. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



4.8.3 Initialization and Default 
Macro takes the form: 

R$KRF numeric 
If there is no initialization macro, KRF = 0. 
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************* 

* * 

* KSZ * 

* * 
************* 



4.9 KSZ 

The one-byte Key Size (KSZ) field contains the size, in bytes, of the 
key buffer indicated by the KBF field. RMS-11 requires specific sizes 
for a relative record number and all Indexed key types except string 
(see "Values"). However, for string keys, RMS-11 uses the number of 
characters specified in KSZ as a length criterion in the index search 
required by the record operation. Therefore, before a search can be 
successful, RMS-11 must find a record with a key value that matches 
the value indicated by KBF to the number of characters indicated by 
KSZ. If KSZ equals the length of the key (established when the file 
was created), the search requires an exact match, whereas when KSZ is 
less than the key length, only an approximate match is needed. 

The value of the ROP field also affects match criteria. 



4.9.1 Use 

Input to: 

$FIND/$GET 

For Relative files, you must set the KSZ field equal to or 
4. 

For Indexed files, you set the KSZ field equal to: 

• specific number of bytes for all key types except string 



$PUT 



• the number of characters in a key field that must match 
the KBF value before the search is successful 

For Relative files, you must set the KSZ field equal to or 
4. 



4.9.2 Input Values 

The values of the KSZ field depend on the type of key indicated bv the 
KBF field: 

• Relative Record Number (FB$REL in FAB ORG field) , KSZ = 4 (0 de- 
faults to 4) 
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• String Key Type (FB$IDX in FAB ORG field): 
MINIMUM = 1 

MAXIMUM = size of key indicated by the KRF field 

• 15-bit Signed Integer Key Type, KSZ = 2 (0 defaults to 2) 

• 31-bit Signed Integer Key Type, KSZ = 4 (0 defaults to 4) 

• 16-bit Unsigned Binary Key Type, KSZ = 2 (0 defaults to 2) 

• 32-bit Unsigned Binary Key Type, KSZ = 4 (0 defaults to 4) 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 

4.9.3 Initialization and Default 
Macro takes the form: 
R$KSZ numeric 

If there is no initialization macro, KSZ = 0, meaning you must set the 

field with the $ST0RE 
field access macro be- 
fore any Indexed random 
record operation. 



4.9.4 Comments 

RMS-11 uses the KSZ field only for Indexed random record operations 
with string keys. 
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************* 

* * 

* MBC * 

* * 
************* 



4.10 MBC 

The one-byte Multi-Block Count (MBC) field contains number of blocks 
from a disk Sequential file that RMS-11 reads or writes as a single 
I/O unit while the Record Access Stream is set up (between $C0NNECT 
and $DISCONNECT) . 



4.10.1 Use 

The MBC field should be set for disk Sequential files only; take the 
default of one for all other files. See also the RMS-11 User's Guide. 

Input to: 

$CONNECT 

You set the MBC field equal to the number of blocks you want 
read from or written to the file in each I/O access opera- 
tion. 



4.10.2 Input Values 

MINIMUM = 0, meaning' one 'block is the I/O unit 

MAXIMUM =63. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 

4.10.3 Initialization and Default 
Macro takes the form: 

R$MBC numeric 
If there is no initialization macro, MBC = 0. 

4.10.4 Comments 

• See the RMS-11 User's Guide for a discussion of the use of MBC in 
optimization. 

Record Access Block (RAB) : MBC 4-15 



The value in the MBC field determines the size of the I/O buffer 
used for the file represented by the FAB indicated by the RAB FAB 
field. See Chapters 1 and 2. 



m^ 
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************* 

* * 

* MBF * 

* * 
************* 



4.11 MBF 

The one-byte Multi-Buffer (MBF) field contains the number of buffers* 
RMS-11 allocates for I/O operations when the Record Access Stream is 
set up ($CONNECT) . 



4.11.1 Use 

The MBF field should be set only for Indexed files, although RMS-11 
uses it for Relative files as well: take the default value of one for 
Relative files. 

Input to: 

$CONNECT 

If you want to cache index Root buckets, set the MBF field 
to a number greater than two to make buffers available (see 
"Values") . 



4.11.2 Input Values 

MINIMUM = 0, meaning RMS-11 allocates the minimum number of buffers 
required by the file organization. Sequential and Rela- 
tive files require one buffer; Indexed files require two 
buffers. 

MAXIMUM = 255 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



4.11.3 Initialization and Default 
Macro takes the form: 

R$MBF numeric 
If there is no initialization macro, MBF = 



*A buffer is one bucket long. 
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4.11.4 Comments 

• The value in the MBF field affects the size of the buffer pool for 
the file. See Chapters 1 and 2. 

• Although RMS-11 does respond to the MBF field for non-Indexed 
files, the use of a value greater than the minimum (other than the 
default) is a waste of address space and the use of a macro to set 
the value. 

• See the RMS-11 User's Guide for a discussion of the use of MBF in 
optimization. 

• The value in the MBF field should incorporate the minimum require- 
ments for the Indexed file: add the number of Roots you want 
cached to the minimum requirements to get the value for the MBF 
field. 

• If the value is: 

— less than minimum, RMS-11 allocates the minimum number of 
buffers 

— more than two for Sequential files, RMS-11 allocates only two 
buffers 

— more than is available, RMS-11 allocates as many buffers as pos- 
sible 
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************* 

* * 

* RAC * 

* * 

************* 



4.12 RAC 

The one-byte Record Access (RAC) field contains an indicator for the 
access method to be used in a record operation. 



4.12.1 Use 

Input to: 

$FIND/$GET/$PUT 

You set the RAC field to indicate the access method RMS-11 
should use to locate the next record position. 



4.12.2 Input Values 

The RAC field must contain one of the following symbolic values: 

RM$KEY RMS-11 performs a random record operation, using specifi- 
cations from the KBF, KSZ , and if necessary KRF and ROP 
fields. Random access applies only to Relative and In- 
dexed files. 

RB$RFA RMS-11 performs a record operation using the Record's 
File Address specified in the RFA field to locate the re- 
cord position. RFA access applies only to disk files. 

RB$SEQ RMS-11 performs a sequential record operation. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



4.12.3 Initialization and Default 
Macro takes the form: 

R$RAC symbolic 
If there is no initialization macro, RAC = RB$SEQ. 
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************* 

* * 

* RBF * 

* * 
************* 



4.13 RBF 

The one-word Record Buffer (RBF) field points to the buffer in the 
program that contains the 
record moved by the record operation. 



4.13.1 Use 

Input to: 

$PUT/$UPDATE 

Regardless of the Record Transfer Mode, you must set the RBF 
field equal to the address of the first byte of the record 
you want written to the file. You must also set the RSZ 
field. 

Output from: 

$GET 

Regardless of Record Transfer Mode, RMS-11 sets the RBF 
field equal to the address of the first byte of the record 
read from the file. The RSZ field is also set. 



$PUT 



When your program is writing records to a Sequential file in 
the Locate Record Transfer Mode, RMS-11 returns an address 
in the RBF field after each $PUT operation. This address is 
the location where your program can build the next record. 
If your program uses this location, it must set the RSZ 
field to describe the record that begins at the location. 
However, if your program does not use the address, it must 
reset both the RBF and RSZ fields. 



4.13.2 Input Values 

The RBF field must contain a valid address. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 
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4.13.3 Initialization and Default 

Macro takes the form: 

R$RBF label 

If there is no initialization macro, RBF = 0, meaning you must set the 

field with $STORE before 
a put or update opera- 
tion is initiated. 



4.13.4 Comments 

During the simplest of processes, that is, in Move Record Transfer 
Mode and the same records are being read and written/updated, the 
RBF/RSZ and UBF/USZ fields describe the same buffer within your pro- 
gram: 

• RBF/RSZ describe the record that RMS-11 moves out of your program 
to the file. 

• UBF/USZ describe the buffer where RMS-11 places each record read 
from the file. 

In anticipation of this common usage, RMS-11 resets RBF after a suc- 
cessful get operation so that you don't have to set it before initiat- 
ing a $UPDATE macro: when RBF and UBF point to the same buffer, RBF 
is not changed. 
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************* 

* * 

* RFA * 

* * 
************* 



4.14 RFA 

The three-word Record's File Address (RFA) field contains the file ad- 
dress of the target record for or from a get or find operation or of 
the record written by a put operation. 



4.14.1 Use 

Input to: 

$FIND/$GET 

If you have set the RAC field to RB$RFA, you set the RFA 
field equal to the Record's File Address of the record you 
want found or read. 

Output from: 

$FIND/$GET 

If the RAC field does not contain RB$RFA, RMS-11 sets the 
RFA field equal to the Record's File Address of the record 
found or read. 

$PUT/$UPDATE 

RMS-11 sets the RFA field equal to the Record's File Address 
where it wrote the record specified. 



4.14.2 Input Values 

If the RAC field contains RB$RFA, the RFA must contain a valid 
Record's File Address for the file; otherwise, error code ER$RFA. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



4.14.3 Initialization and Default 
Macro takes the form: 

R$RFA numeric 
If there is no initialization macro, RFA = 0. 
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************* 
* * 

* RHB * 

* * 
************* 



4.15 RHB 

The one-word Record Header Buffer (RHB) field points to the buffer in 
the program containing the fixed control area of 
Variable-with-Fixed-Control (VFC) records. When RMS-11 gets a record, 
it separates the fixed control area from the variable portion of the 
record; it places the fixed data in the buffer indicated by the RHB 
field and the variable data in the buffer indicated by the UBF field. 
For put operations, RMS-11 prefixes the data from the RHB buffer to 
the data in the RBF buffer before it moves the entire record from the 
program to the I/O buffer and then to the file. 

If no RHB buffer is indicated (the RHB field is zero) , but the file 
contains VFC records (FB$VFC in the FAB RFM field) , RMS-11 does the 
following : 

• ignores the fixed control area of records read ($GET) from the file 

• fills the fixed control area of records written ($PUT) to the file 
with zeros 

• does not change the fixed control area of records during update op- 
erations 



4.15.1 Use 



Input to: 

$GET/$PUT/$UPDATE 

• If you want the fixed control area of each record read 
and written properly, set the RHB field equal to the ad- 
dress of a buffer in the program. 

• If you do not want the fixed control area of each record 
read or written, ensure that the RHB field is zero; 
otherwise, RMS-11 interprets the value in the field as an 
address and tries to use the area indicated as a buffer: 
the results are unpredictable. 



4.15.2 Input Values 

The RHB field must contain either: 

• zero (0) = there is no buffer for the fixed control area 
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• address of the fixed control area buffer. This buffer must be at 
least as long as the value* in the FAB FSZ field indicates. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



4.15.3 Initialization and Default 
Macro takes the form: 

R$RHB label 
If there is no initialization macro, RHB = 0. 

4.15.4 Comments 

During Locate Mode operations, the variable area data is accessed in 
the I/O buffer, but the data in the fixed control area is moved to and 
from the buffer described by the RAB RHB and FAB FSZ fields. 



*This value is a file attribute established when the file was created 
and set in the FAB FSZ field by the file open process. 
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************* 

* * 

* ROP * 

* * 
************* 



4.16 ROP 

The one-word Record Processing Options (ROP) field contains a bit 
string indicating optional functions that you want RMS-11 to perform 
while this Record Access Stream is set up (between $CONNECT and 
$DISCONNECT) . 



4.16.1 Use 



Input to : 

$CONNECT/$DELETE/$FIND/$GET/$PUT 

You set the ROP field to indicate the optional functions you 
want RMS-11 to perform. 



4.16.2 Input Values 

The ROP field may contain one or more of the following symbolic 
values : 

RB$ASY RMS-11 performs an asynchronous record operation, possi- 
bly returning control to your program before the opera- 
tion is completed. The RAB must have been defined as as- 
ynchronous type by the RAB$B macro (see "Allocation" at 
the beginning of this chapter). 

RB$EOF RMS-11 sets the context of the stram at the end of the 
file when the $CONNECT macro is finished; valid for disk 
Sequential files only. This feature enables you to op- 
timize buffer space: when you are adding records to a 
Sequential file, you can: 

• disconnect the Record Access Stream when you are not 
using the file. This operation releases buffer space 
for use by other operations. 

• connect the Record Access Stream at end-of-file, ready 
to put another record. 

RB$FDL RMS-11 uses the Fast Delete procedure; valid for Indexed 
files only. During $DELETE execution, RMS-11 flags the 
user data record in the file as being deleted, but it up- 
dates Alternate indexes depending on whether duplicates 
are allowed: 
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• If duplicates are allowed, the SIDR array entry for 
the deleted record is NOT flagged as deleted. 
Thereafter, a find or get operation using that key 
value for that Alternate index will go to the Primary 
Level bucket before it detects that the record has 
been deleted. 

• If duplicates are not allowed, the SIDR is removed 
from the Alternate Level bucket. 

RB$KGE RMS-ll's search during a find or get operation depends on 
file organization: 

• In Relative files, RMS-11 checks the cell specified by 
the relative record number in the RAB KBF field; if 
the cell contains a valid record, the search ends. 
However, if the cell is empty or contains a deleted 
record, RMS-11 continues searching sequentially 
through the cells until it finds a valid record, en- 
counters end-of-file, or exceeds the Maximum Record 
Number . 

• In Indexed files, RMS-11 searches for the first record 
containing a value in the key specified by the KRF 
field that is greater than or equal to the value des- 
cribed by the KBF and KSZ fields. 

RB$KGT RMS-ll's search during a find or get operation depends on 
file organization: 

• In Relative files, RMS-11 starts at the cell with a 
relative record number one higher than the number in 
the RAB KBF field and searches sequentially through 
the cells until it finds a valid record, encounters 
end-of-file, or exceeds the Maximum Record Number. 

• In Indexed files, RMS-11 searches for the first record 
containing a value in the key specified by the KRF 
field that is greater than the value described by the 
KBF and KSZ fields. 

RB$MAS indicates to RMS-11 that you intend to insert a series of 
records at the logical end of an Indexed file. These re- 
cords must be sorted in ascending order by the Primary 
Key value, and the lowest Primary Key value in the ser- 
ies, that of the first record, must be higher than any 
Primary Key value already in the file. To implement Mass 
Insert, RMS-11 keeps the data bucket locked after the 
$PUT operation ends and maintains a pointer into the 
index bucket above the data bucket in the index. This 
effort enables RMS-11 to rapidly insert records into the 
file, splitting buckets economically if necessary. The 
presence of Alternate Keys degrades this performance. 
Activating Deferred Write (FB$DFW) enhances it. 
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RB$LOA RMS-11 obeys bucket fill numbers when it is inserting re- 
cords; valid for Indexed files only. See Allocation XAB 
DFL and IFL fields and the RMS-11 User's Guide. 

RB$LOC RMS-11 uses the Locate Record Transfer Mode for get oper- 
ations on all file organizations and for put operations 
for Sequential files only. See the RMS-11 User's Guide. 

RB$UIF If RMS-11 encounters a record in the target cell during a 
put operation, it updates the record rather than return- 
ing error code ER$REX; valid for Relative files only. 

If you want to specify more than one option, you must concatenate the 
values using an exclamation point (!). 

A value can be set in the field with the initialization macro shown 
below or with the $SET field access macro (see Chapter 7). 



4.16.3 Initialization and Default 
Macro takes the form: 

R$ROP symbolic [! symbol ic. .. ] 
If there is no initialization macro, ROP = 0, meaning: 

• Synchronous record operation 

• Context in a disk Sequential file after $CONNECT is the first re- 
cord in the file. 

• RMS-11 removes SIDR duplicate array entries from Alternate indexes 
during delete operations on Indexed files. 

• RMS-11 requires that a record's key value be equal to the value 
specified by the KBF and KSZ fields before it returns the record to 
the task. 

• RMS-11 completely fills Indexed file buckets. 

• Move Record Transfer Mode 

• If RMS-11 encounters a record in the target cell during a put oper- 
ation on a Relative file, it returns error code ER$REX. 



4.16.4 Comments 

Since the ROP field is a bit string, values cannot be added to the 
field with the $ST0RE field access macro. You should use the $SET 
field access macro (see Chapter 7). However, you use the $STORE macro 
to (re) set all bits in the field. 
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************* 

* * 

* RSZ * 

* * 
************* 



4.17 RSZ 

The one-word Record Size (RSZ) field contains the size, in bytes, of 
the record indicated by the RBF field. 



4.17.1 Use 

Input to: 

$PUT/$UPDATE 

You set the RSZ field equal to the size of the record in the 
record buffer indicated by the RBF field. RMS-11 moves only 
the number of bytes specified. 

Output from: 

$GET 

RMS-11 sets the RSZ field equal to the length of the record 
it placed in the buffer indicated by the UBF field. 



4.17.2 Input Values 
MINIMUM = 1 

MAXIMUM = 65535, but maximum record size is also affected by file 

structure, file organization, and task address space. 
See the RMS-11 User's Guide. 

A value of is valid for only Sequential and Relative files with stre- 
am or variable-length records. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 
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4.17.3 Initialization and Default 
Macro takes the form: 

R$RSZ numeric 
If there is no initialization macro, RSZ 



0, meaning you must set the 
field with the $STORE 
field access macro be- 
fore a $PUT operation* 
is initiated. 



NOTE 



RSZ is also input to the $UPDATE macro; however, an update 

a get (or find) : that opera- 
don* t have to set it before 
record size changes. 



operation must be preceded by 
tion sets the RSZ field so you 
update operation unless the 



an 
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************* 

* * 

* STS * 

* * 
************* 



4.18 STS 

The one-word Completion Status Code (STS) field contains a code indi- 
cating the success or failure (and type of failure) of the last record 
operation. See Appendix A for symbolic and octal codes for both suc- 
cess and failure of operations. 



4.18.1 Use 

Output from: 

$CONNECT/$DELETE/$DISCONNECT/$FIND/$GET/$PUT/$UPDATE/$REWIND/ 

$TRUNCATE/$FLUSH/$NXTVOL 

RMS-11 sets the STS field equal to a completion status code. 
You should test this field ($COMPARE field access macro) for 
a negative value after each record operation, or you can use 
an error routine that checks the value (see Chapter 8). 



4.18.2 Input Values 

No input values; see Appendix A for output values. 
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************* 

* * 

* stv * 

* * 
************* 



4.19 STV 

The one-word Status Value (STV) field contains additional information 
about some error codes returned in the STS field. 



4.19.1 Use 

Output from: 

$CONNECT/$DELETE/$DISCONNECT/$FIND/$GET/$PUT/$UPDATE/$REWIND/ 

$TRUNCATE/$FLUSH/$NXTVOL 

RMS-11 sets the STV field whenever it had additional infor- 
mation to communicate about an error. See Appendix A for 
the specific errors on which the STV field is used. You 
should check the STV field for a nonzero value whenever your 
program detects an error (negative value in STS field) . 



4.19.2 Input Values 

No input values; see Appendix A for output values. 
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************* 

* * 

* UBF * 

* * 
************* 



4.20 UBF 

The one-word User Buffer (UBF) field points to a buffer in your pro- 
gram where RMS-11 should place a record read from the file or that 
RMS-11 can use during Locate Mode if necessary. 



4.20.1 Use 

Input to: 

$C0NNECT 

RMS-11 transfers the address in the UBF field to the RBF 
field so that your program does not have to treat the first 
put in Locate Mode on a Sequential file as a special case. 

$GET 

Regardless of Record Transfer Mode (RTM) , you set the UBF 
field equal to the address of the first byte of the record 
buffer you have provided for RMS-11 to store the record it 
reads from the file: 

• In Move RTM, RMS-11 automatically places the retrieved 
record in the buffer indicated by UBF. 

• In Locate RTM, RMS-11 normally leaves the retrieved re- 
cord in the stream's I/O buffer and then sets the RBF 
field to its address. However, RMS-11 can determine that 
it cannot perform the record operation in Locate mode 
(see UG): it then moves the record into the buffer indi- 
cated by UBF. 

In either circumstance, if the buffer described by UBF is 
too small to contain the retrieved record, RMS-11 moves as 
much of the record as possible into the buffer (the number 
of bytes in the USZ field) , updates the context of the stre- 
am, and returns error code ER$RTB 

During Locate Mode operations on Sequential files only, UBF 
must continue to point to a valid record buffer within your 
program. Normally after a put operation, RMS-11 sets the 
RBF field to the address of a location in the stream's I/O 
buffer where your program can build the next record. 
However, if there is not enough room in the buffer to con- 
tain another record (based on the value in the FAB MRS 
field) , RMS-11 changes RBF to UBF, thereby pointing your 
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$PUT 
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program to the user buffer to build the next record. Then, 
during the next put, RMS-11 fills out the current I/O buffer 
from the UBF buffer, writes the I/O buffer to the file, and 
then starts a new I/O buffer with the data left in the UBF 
buffer, setting RBF back into the I/O buffer. 



4. 20. 2 Input Values 

The UBF field must contain the address of a buffer in your program. 
The buffer should be large enough to contain the largest record in the 
file. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



4.20.3 Initialization and Default 
Macro takes the form: 

R$UBF label 
If there is no initialization macro, UBF = 0. 
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************* 

* * 

* usz * 

* * 
************* 



4.21 USZ 

The one-word User Buffer Size (USZ) field contains the size, in bytes, 
of the buffer indicated by the UBF field. 



4.21.1 Use 



Input to: 
$GET 



$P-UT 



You set the USZ field equal to the size of the buffer you 
are providing to hold a record. RMS-11 reads in only the 
number of bytes specified. 



During Locate Mode operations on Sequential files only. See 
discussion under "Use" for the UBF field. 



4. 21. 2 Input Values 

MINIMUM = 1 

MAXIMUM = 65535, but maximum record size is also affected by file 

structure, file organization, and task address space. 
See the RMS-11 User's Guide. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



4.21.3 Initialization and Default 
Macro takes the form: 

R$USZ numeric 
If there is no initialization macro, USZ 



= 0, 
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CHAPTER 5 
EXTENDED ATTRIBUTE BLOCKS 



The initialization macros (this chapter) and the field access macros 
(Chapter 7) are provided so that you do not have to know the specific 
position and to a large extent, the size of each field in a XAB. You 
can, therefore, treat the fields as logical entities. It is also pos- 
sible that the positions and sizes of the fields will change from re- 
lease to release of RMS-11. 

However, you can determine the position of any field in a XAB as an 
offset from the XAB * s starting address. RMS-11 represents these off- 
set values with symbols in one of the following forms: 

• 0$fnm 

where fnm is the three-letter name of a one-byte or one-word field; 
fnm is the name used to reference the field in the initialization 
and field access macros. 

Example 0$STS for the status code field 

• 0$fnmx 

where fnm is the name of a multiword field; fnm is the name used 
to reference the field in the initialization and field 
access macros. 

x is a number associated with an individual word in the 
field, from through the end of the field. 

Example 0$SIZO for the size of the first segment in a key as the 
most significant word 

The values of these symbols can be found in the symbol table of an as- 
sembly listing file for any module containing the XAB. 



5.1 Allocation Extended Attribute Block 

Each Allocation XAB describes an area of a file. An area is a portion 
of an RMS-11 file that is treated as a separate entity for purposes 
of: 

Initial allocation 
Extension 
Placement 
Bucket size 

See also the RMS-11 User's Guide. 

Sequential and Relative files are always composed of a single area 
(Area 0), while Indexed files should contain more than one area. 

Allocation XABs enable you to control: 

• The physical placement of an RMS-11 file of any organization on a 
disk volume: 

You provide one (for any type of file) or more (for Indexed files 
only) Allocation XABs linked to the FAB you use to create the file. 
Within each XAB are two fields: 

Alignment Block Type (ALN) 
Allocation Starting Point (LOC) 

If the ALN field is not zero when the $CREATE macro is executed, 
RMS-11 uses the values in the two fields to direct the placement of 
the first block of the area on the device specified; the XAB ALQ 
field controls the size of the initial allocation. 

NOTE 

On RSTS/E, the File Processor allows RMS-11 to place only 
Area 0. RMS-11 allocates all other areas as extents of 
Area 0. See also comments for the AOP field in this sec- 
tion. 



• The internal structure of an Indexed file: 

Whether or not you use placement control, you can use Allocation 
XABs to define multiple areas within an Indexed file, assign the 
index and data levels of the various indexes to particular areas, 
and vary the size of buckets for each area. 

Allocation XABs are completely optional. If you do not require either 
placement control or an optimized Indexed file, do not include Alloca- 
tion XABs in your XAB chain; RMS-11 uses the following defaults: 

• RMS-11 creates the file as a single area, using the value in the 
FAB ALQ for the initial allocation quantity. The default extension 
quantity is derived from the FAB DEQ field. The operating system 
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completely 
volume. 



controls the physical placement of the file on the disk 



For Indexed files, RMS-11 sets up a single bucket size and 
buckets of all types (index, SIDR, and user data record) 
single area of the file. 



stores 
in the 



If you do use Allocation XABs , they are used 



as : 



Input to $CREATE and $EXTEND 
Before the initiation of 
XABs must be set up and 
dense ascending order by 
be the first Allocation 
1 must be next; and so on 
must point to Area l's 
point to Area 2's XAB, and 



a $CREATE macro, all Allocation 
included in the XAB chain linked in 
AID field: the XAB for Area must 
XAB in the chain; the XAB for 



The NXT field for Area O's 
XAB, Area l's XAB NXT field 
so on. 



Area 
XAB 
must 



Output from $DISPLAY, $EXTEND, and $OPEN 

If you want one or more area definitions, link a sufficient 
number of Allocation XABs. RMS-11 sets the appropriate 
fields to the values established when the file was created. 
The Allocation XABs must be adjoining, linked in ascending 
order, but they do not have to be densely ordered. 
Therefore, you can link Allocation XABs for Areas 1 and 3 
only, for example, if descriptions of those areas are the 
only ones you want. 



NOTE 

Since RMS-11 creates a file with areas by allocating Area 
first and then extending the file for each additional area, 
you can't have a contiguous file with multiple areas on 
RSTS/E. However, after you create the file with areas, you 
can use PIP to copy it into a contiguous space. 



Table 5-1: Allocation Extended Attribute Block Fields 



Field 
Name 



AID 
ALN 
ALQ 
AOP 
BKZ 
BLN 
COD 
DEQ 
LOC 
NXT 
VOL 



Field 
Si ze 



IB 
IB 
2W 
IB 
IB 
IB 
IB 
1W 
2W 
1W 
1W 



Default 










record 
N/A 
N/A 











Description 



Area id number 

Alignment block type 

Allocation quantity 

Allocation options 

Area bucket size 

All XAB length 

XAB type 

Area extension quantity 

Number of block specified by ALN 

Next XAB 

Not used 
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************* 

* * 

* AID * 

* * 
************* 



5.1.1 AID 

The one-byte Area Identification Number (AID) field identifies the 
area described by the XAB. 



5.1.1.1 Use 

Input to: 

$CREATE/$EXTEND 

You set the AID field to tell RMS-11 the area defined by the 
XAB. 

$DISPLAY/$OPEN 

You set the AID field to tell RMS-11 the area whose descrip- 
tion it should set into the fields of the XAB. 

Additionally, RMS-11 uses the AID field to check the sequencing of the 
Allocation XABs in the chain before continuing with the file 
operation; if the XABs are out of sequence, RMS-11 terminates the op- 
eration. 



5.1.1.2 Input Values 

MINIMUM = 0* 

MAXIMUM = 254 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.1.1.3 Initialization and Default - Macro takes the form: v 

X$AID numeric 
If there is no initialization macro, AID = 0. 



*Zero is the only value acceptable for Sequential and Relative files. 
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************* 

* * 

* ALN * 

* * 
************* 



5.1.2 ALN 

The one-byte Alignment Block Type (ALN) field determines whether 
placement control is used in the allocation of blocks in this area by 
the file operation. 



5.1.2.1 Use 
Input to: 

$CREATE 

• If you want placement control over the initial allocation 
of the area, you set the ALN field to indicate that the 
number in the LOC field is one of the following: 

Device Cluster Number 
Logical Block Number 
Virtual Block Number 
Cylinder number on VAX 

The AOP field also affects placement control. 

• If you do not want placement control, you set the ALN 
field to zero. 

$EXTEND 

• If you want placement control over the explicit extension 
of the area, you set the ALN field to indicate that the 
block number in the LOC field is either a Logical Block 
Number or a Virtual Block Number. The AOP field also af- 
fects placement control. 

• If you do not want placement control, you set the ALN 
field to zero . } 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the ALN field equal to the value specified when 
the file was created. 
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5.1.2.2 Input Values - The ALN field must contain one of the follow- 
ing : 

zero no placement control 

XB$LBN RMS-11 requests the operating system to place the first 

block of the specified allocation on or near the logical 

block / device cluster indicated by the number in the 
LOC field. 

XB$VBN RMS-11 requests the operating system to place the first 
block of the specified allocation near the virtual block 
of the file indicated by the LOC field; not valid during 
$CREATE when the AID field is zero, that is, for Area 0. 

XB$CYL RMS-11 requests the operating system to place the first 
block of the specified allocation at the first block of a 
cylinder as indicated by the LOC field. VAX only 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.1.2.3 Initialization and Default - Macro takes the form: 

X$ALN symbolic 
If there is no initialization macro, ALN = 0. 



5.1.2.4 Comments - On RSTS/E, you can specify location information 
for Area only. If RMS-11 detects nonzero values in the ALN and LOC 
fields in other Allocation XABs , it returns the error code ER$ALQ. 
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************* 

* * 

* ALQ * 

* * 
************* 



5.1.3 ALQ 

The two-word Allocation Quantity (ALQ) field contains the size of the 
area represented by the XAB, in blocks. 



5.1.3.1 Use 

Input to: 

$CREATE 

You set the ALQ field equal to the number of blocks to be 
allocated in the initial extent of the area. 

$EXTEND 

You set the ALQ field equal to the number of blocks to be 
added to the area. 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the ALQ field equal to the number of blocks un- 
used in the current extent of the area (see "Comments"). 
RMS-11 obtains this information from the file Prologue. 



5.1.3. 2 Input Values 

$CREATE 

MINIMUM = 0, meaning that this area will only be as long as ne- 
cessary; that is, Area will contain the file Pro- 
logue and all other areas will be allocated with no 
blocks. 

MAXIMUM = number of free blocks on the device containing the 
file. 

$EXTEND 

MINIMUM = 1, meaning that one block should be added to the area 
(although a zero extent is possible, it is not logi- 
cal) 

MAXIMUM = number of free blocks on the device containing the 
area . 
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RMS-11 rounds values up to a multiple of area bucket size. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.1.3.3 Initialization and Default - Macro takes the form: 
X$ALQ numeric 

If there is no initialization macro, ALQ = 0. 

5.1.3.4 Comments 

• When Allocation XAB(s) are linked to a FAB, create and extend oper- 
ations ignore the FAB ALQ field, using the XAB ALQ field (s) for the 
particular area(s). If you include only one Allocation XAB, for 
Area 0, RMS-11 uses the ALQ field in the XAB instead of the FAB for 
the size of Area 0, which is essentially the whole file. 

• The current extent of an area is the number of blocks that were 
last added to the area, via either automatic or explicit extension. 
It is, therefore, not necessarily the total size of the area. 
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************* 

* * 

* AO p * 

* * 
************* 



5.1.4 AOP 

The one-byte Allocation Options (AOP) field contains a bit string in- 
dicating the type of allocation RMS-11 makes during the file opera- 
tion. 



5.1.4.1 Use 

Input to $CREATE/$EXTEND: 

You set the AOP field to indicate how exact you require the actu- 
al alignment of the area's allocation with the value specified in 
the LOC field. 

Output from $DISPLAY/$OPEN: 

RMS-11 sets the AOP field equal to the value specified when the 
file was created. 



5.1.4.2 Input Values - The AOP field may contain one or both of the 
following symbolic values: 

XB$HRD The operation fails unless the allocation starts exactly 
at the Device Cluster /Logical Block Number specified by 
the LOC field; valid only if the ALN field contains 
XB$LBN. 

XB$CTG The operation fails unless the allocation is contiguous 
within itself. 

A value can be set in the field with the initialization macro shown 
below or with the $SET field access macro (see Chapter 7). 



5.1.4.3 Initialization and Default - Macro takes the form: 

X$AOP symbolic [! symbolic] 
If there is no initialization macro, AOP = 0, meaning: 

• Allocation is made as close to the requested block as possible. 

• Allocation is not necessarily contiguous with the current extent of 
the area. 
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************* 

* * 

* BKZ * 

* * 
************* 



5.1.5 BKZ 

The one-byte Bucket Size (BKZ) field contains the size of a bucket, in 
disk blocks, in the area represented by the XAB. 



5.1.5.1 Use - RMS-11 uses the BKZ field for Relative and Indexed 
files. 

Input to: 

$CREATE 

You set the BKZ field equal to the number of disk blocks in 
a bucket for the area to be created. 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the BKZ field equal to the bucket size esta- 
blished for the area when the file was created. RMS-11 ob- 
tains the information from the file Prologue. 



5.1.5.2 Input Values - 

MINIMUM = 0, meaning that RMS-11 calculates a size so that a bucket 
contains at least one record. 

MAXIMUM -• number of blocks allowed by the operating system (specifying 
a larger value results in error code ER$BKZ) : 

IAS = 32 blocks 

RSTS/E = 15 blocks 

RSX-11M = 32 blocks 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.1.5.3 Initialization and Default - Macro takes the form: 

X$BKZ numeric 

If there is no initialization macro, BKZ = minimum number of blocks to 

contain one record. 
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5.1.5.4 Comments - 

• When Allocation XABs are linked to a FAB, RMS-11 ignores the FAB 
BKZ field, using the XAB BKZ fields for the particular areas. 

• You gain no particular advantage from different bucket sizes for 
different areas. 



Allocation XAB: BKZ 5-11 



************* 

* * 

* BLN * 

* * 
************* 



5.1.6 BLN 

The XAB$B macro sets the one-byte Block Length (BLN) field to the Ex- 
tended Attribute Block length. 

CAUTION 
DO NOT CHANGE THE BLN FIELD. 



fflW?ifflj|, 



5.1.6.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the BLN field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ER$BLN error code. 
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************* 

* * 

* COD * 

* * 
************* 



5.1.7 COD 

The XAB$B macro sets the one-byte Code (COD) field to the Extended At- 
tribute Block type, with the symbolic value of XB$ALL. 

CAUTION 
DO NOT CHANGE THE COD FIELD. 



5.1.7.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the COD field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ER$COD error code. 
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************* 

* * 

* DEQ * 

* * 
************* 



5.1.8 DEQ 

The one-word Default Extension Quantity (DEQ) field contains the 
number of blocks RMS-11 requests whenever it automatically extends the 
area (opposed to an explicit extend operation). RMS-11 requests addi- 
tional blocks from the operating system* whenever a task attempts a 
put or update operation and there is not enough room in the area re- 
presented by the XAB to complete the operation. 



5.1.8.1 Use - RMS-11 uses the DEQ field for Indexed files only. 

Input to: 

$CREATE 

You set the DEQ field equal to the number of blocks that 
should be requested in each automatic extension of the area 
to be created. 

$OPEN 

You set the DEQ field equal to the number of blocks to be 
used by RMS-11 as a temporary default extension quantity 
until the area is closed; the area attribute is not 
changed . 

Output from: 

$OPEN 

If the DEQ field is zero, RMS-11 sets it equal to the number 
of blocks established as the default extension quantity when 
the area was created. 



5.1.8.2 Input Values - Default extension quantity should be a multi- 
ple of bucket size; RMS-11 rounds it up to the nearest multiple any- 
way before it sends the extension request to the operating system. 

MINIMUM = 0, meaning that whenever RMS-11 has to extend the area, it 
will request the minimum blocks necessary to complete the 
current operation, that is, one bucket. 

MAXIMUM = 65,535 blocks 

♦Automatic extension can fail;see "Comments." 
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RMS-11 rounds value up to a multiple of area bucket size. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.1.8.3 Initialization and Default - Macro takes the form: 
X$DEQ numeric 

If there is no initialization macro, DEQ = 0. 

5.1.8.4 Comments 

• When Allocation XABs are linked to a FAB, RMS-11 uses the XAB DEQ 
field whenever an area has to be extended automatically, unless 
that field is zero; in that case, RMS-11 uses the value in the FAB 
DEQ field. 

• Automatic extension can fail for at least the following reasons; 
there might be others: 

— Operating system is RSTS/E and file is: 

contiguous; error code = ER$PRV 
shared; error code = ER$PRV 

— No more room is available on the storage device; error code = 
ER$FUL 

• On the RSTS/E operating system, area allocation is done in 
clusters; see the RMS-11 User's Guide for a discussion of the in- 
teraction between clusters and default extension quantity. 

• See the RMS-11 User's Guide for a discussion of default extension 
quantity and its optimization. 
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************* 

* * 

* LOC * 

* * 
************* 



5.1.9 LOC 

The two-word Allocation Starting Point (LOC) field contains a number 
interpreted by RMS-11 as the Device Cluster , Logical Block, Virtual 
Block, or cylinder number (depending on the value of the ALN field) 
where the allocation specified by the operation should start. The ALQ 
field specifies the allocation quantity and the AOP field indicates 
how definite the placement is. 



5.1.9.1 Use 

Input to: 

$CREATE/$EXTEND 

If you specify a nonzero value for the ALN field, you must 
set the LOC field equal to the appropriate number (depending 
on the value in the ALN field) where you want the specified 
allocation to begin. 



5.1.9.2 Input Values - The LOC field must contain one of the follow- 
ing : 

• any value* if the ALN field is zero 

• numeric value within the range: 

MINIMUM = 0; if the ALN field contains XB$VBN, RMS-11 requests 
placement near the current end of the file, unless AID 
is zero. 

MAXIMUM = number of free blocks / clusters on the device contain- 
ing the file, if the ALN field contains XB$LBN 

= number of cylinders on the device containing the file, if 
the ALN field contains XB$CYL 

= number of blocks currently in the file, if the ALN field 
contains XB$VBN 

• the numeric value -1 if the ALN field contains XB$CYL; RMS-11 re- 
quests placement at the first block of any cylinder 



♦Recommended value is the default, zero. 
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A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.1.9.3 Initialization and Default - Macro takes the form: 

X$LOC numeric 
If there is no initialization macro, LOC = 0. 
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************* 

* * 

* NXT * 

* * 
************* 



5.1.10 NXT 

The one-word Next XAB (NXT) field, if not zero, points to another sep- 
arately allocated XAB and thereby indicates to RMS-11 that there is at 
least one more XAB in the chain connected to the FAB via the FAB XAB 
field. See "Linking and Ordering XABs" at the beginning of this 
chapter. 



5.1.10.1 Use 
Input to: 

$CREATE/$DELETE/$EXTEND/$OPEN 

• If you have allocated another XAB and want RMS-11 to use 
it, you set the NXT field equal to the address of that 
XAB. 

• If you have not allocated an XAB and/or you want the XAB 
chain to end here, set the NXT field equal to zero; 
otherwise, RMS-11 interprets the value in the field as an 
address and tries to use the area indicated as an XAB: 
if that area is not a valid XAB, RMS-11 returns the error 
code ER$XAB. 



5.1.10.2 Input Values - The NXT field must contain either: 

• zero (0) = there are no more XABs in this chain 

• address of an Extended Attribute Block separately allocated in the 
program 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.1.10.3 Initialization and Default - Macro takes the form: 

X$NXT label 
If there is no initialization macro, NXT = 0. 
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************* 

* * 

* VOL * 

* * 
************* 



5.1.11 VOL 

The one-word Relative Volume Number (VOL) field is currently not used 
by RMS-11. 



5.1.11.1 Use - NONE 



5.1.11.2 Input Values - NONE 



5.1.11.3 Initialization and Default - NONE 



5.1.11.4 Examples - NONE 



5.1.11.5 Comments - NONE 
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5.2 Date Extended Attribute Block 



The Date XAB contains date and time information about the creation and 
revision of the file, as well as an RMS-11 revision number. The in- 
formation is output only by RMS-11 during a $DISPLAY or $OPEN opera- 
tion; RMS-11 obtains the data from the file attributes. 



Table 5-2: Date Extended Attribute Block Fields 



Field 


Field 


Default 


Description 


Name 


Si ze 






BLN 


IB 


N/A 


DAT XAB length 


CDT 


4W 


N/A 


Creation date-time 


COD 


IB 


N/A 


XAB type 


NXT 


1W 





Next XAB 


RDT 


4W 


N/A 


Revision date-time 


RVN 


1W 


N/A 


RMS-11 revision number 
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************* 

* * 

* BLN * 

* * 
************* 



5.2.1 BLN 

The XAB$B macro sets the one-byte Block Length (BLN) field to the Ex- 
tended Attribute Block length. 

CAUTION 
DO NOT CHANGE THE BLN FIELD. 



5.2.1.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the BLN field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ER$BLN error code. 
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************* 

* * 

* CDT * 

* * 
************* 



5.2.2 CDT 

The four-word Creation Date (CDT) field contains the date and time the 
file associated with the linked FAB was created. 



5.2.2.1 Use 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the CDT field equal to the creation date it 
finds in the file attributes. 



5.2.2.2 Output Values - The value RMS-11 puts into the CDT field is 
an eight-byte binary number representing the number of hundreds of na- 
noseconds that elapsed between November 17, 1858*, and the time the 
file was created. 

This method of storing dates is standard for DIGITAL operating sys- 
tems, although it has not been implemented in IAS, RSTS/E, or RSX-11M 
yet**. RMS-11 translates the dates these operating systems do main- 
tain into the 64-bit format before storing it in the Date XAB. The 
resultant date is only as accurate as the operating system date: 



IAS 


accurate 


to 


the 


second 


RSTS/E 


accurate 


to 


the 


minute 


RSX-11M 


accurate 


to 


the 


second 



Appendix C contains a MACRO-11 routine for converting this 8-byte bi- 
nary number to ASCII characters; this is the same routine used by 
RMSDSP (see the RMS-11 User's Guide). 



*The Smithsonian Astrophysical Base Date, celebrating the day the 
first photographic plate was exposed at the Harvard Smithsonian Ob- 
servatory. 

**It has been implemented in the VAX/VMS System. 
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************* 

* * 

* COD * 

* * 
************* 



5.2.3 COD 

The XAB$B macro sets the one-byte Code (COD) field to the Extended At- 
tribute Block type, with the symbolic value of XB$DAT. 

CAUTION 
DO NOT CHANGE THE COD FIELD. 



5.2.3.1 Use - Before RMS-11 uses an XAB during a file operation, it 

verifies that the block is a valid XAB; one of the checks examines 

the COD field. If this field does not contain the proper code, RMS-11 

terminates the operation with a ER$COD error code. 
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************* 

* * 

* NXT * 

* * 
************* 



5.2.4 NXT 

The one-word Next XAB (NXT) field, if not zero, points to another sep- 
arately allocated XAB and thereby indicates to RMS-11 that there is at 
least one more XAB in the chain connected to the FAB via the FAB XAB 
field. See "Linking and Ordering XABs" at the beginning of this 
chapter. 



5.2.4.1 Use 



Input to: 

$CREATE/$DELETE/$EXTEND/$OPEN 



If you have allocated another XAB and want RMS-11 to use 
it, you set the NXT field equal to the address of that 
XAB . 

If you have not allocated an XAB and/or you want the XAB 
chain to end here, set the NXT field equal to zero; 
otherwise, RMS-11 interprets the value in the field as an 
address and tries to use the area indicated as an XAB: 
if that area is not a valid XAB, RMS-11 returns error 
code ER$XAB. 



5.2.4.2 Input Values - The NXT field must contain either: 

• zero (0) = there are no more XABs in this chain 

• address of an Extended Attribute Block separately allocated in the 
program 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



i^^*^FflBfc 



5.2.4.3 Initialization and Default - Macro takes the form: 

X$NXT label 
If there is no initialization macro, NXT = 0. 
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************* 

* * 

* RDT * 

* * 
************* 



5.2.5 RDT 

The four-word Revision Date (RDT) field contains the date and time the 
file associated with the linked FAB was last updated, that is, the 
date and time the last write record operation* was executed against 
the file. 



5.2.5.1 Use 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the RDT field equal to the revision date it 
finds in the file header. 



5.2.5.2 Output Values - The value RMS-11 puts into the CDT field is 
an eight-byte binary number representing the number of hundreds of na- 
noseconds that elapsed between November 17, 1858**, and the time the 
file was created. 

This method of storing dates is standard for DIGITAL operating sys- 
tems, although it has not been implemented in IAS, RSTS/E, or RSX-11M 
yet***. RMS-11 translates the dates these operating systems do main- 
tain into the 64-bit format before storing it in the Date XAB. The 
resultant date is only as accurate as the operating system date: 

IAS accurate to the second 
RSTS/E accurate to the day 
RSX-11M accurate to the second 

Appendix C contains a MACRO-11 routine for converting this 8-byte bi- 
nary number to ASCII characters; this is the same routine used by 
RMSDSP (see the RMS-11 User's Guide). 



♦Includes RMS-11 delete, put, and update operations and any non-RMS-11 
operations, such as FCS, BASIC+, and utilities (PIP and so on). 
Since higher-level language statements eventually break down to 
RMS-11 macros, the revision date is valid no matter the source 
language of the program doing the file revision. 
**The Smithsonian Astrophysical Base Date, celebrating the day the 
first photographic plate was exposed at the Harvard Smithsonian Ob- 
servatory. 
***It has been implemented in the VAX/VMS System. 
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************* 

* * 

* RVN * 

* * 
************* 



5.2.6 RVN 

RMS-11 returns valid data to the RVN field only on IAS and RSX-11M op- 
erating systems. On RSTS/E systems, this field is always zero. The 
one-word Revision Number (RVN) field indicates the number of times the 
file has been opened for write operations by RMS-11* and non-RMS-11 
tasks since it was created (that open is therefore not counted) . 



5.2.6.1 Use 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the RVN field equal to the revision number it 
finds in the file header. 



5.2.6.2 Input Values - The value stored in the RVN field is a simple 
binary number, easily translated to octal or decimal (see subroutines 
in the sample program in Appendix B) . 



*If the FAB FAC field contains FB$DEL, FB$PUT, FB$UPD, and/or FB$WRI, 
the operating system increments the revision number in the file 
header during an open operation. 
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5.3 Key Extended Attribute Block 

A Key XAB describes one key of an Indexed file. This includes specif- 
ications for the key field (type, position, length) as well as the 
index structure supporting that key. See the RMS-11 User's Guide. 

Key XABs are used as: 

Input to $CREATE 

Before the initiation of a $CREATE macro, if the FAB ORG 
field contains FB$IDX, you must link at least one Key XAB to 
the FAB to define the Primary Key. You must also use one 
Key XAB to define each additional key you want the file to 
have. If you specify more than one Key XAB, they must be: 

• linked in densely ascending order by REF field; that is, 
the Primary Key XAB is the first Key XAB to occur in the 
chain, the First Alternate Key XAB next, and so on 

• adjoining in the XAB chain; that is, the Primary Key XAB 
NXT field points to the First Alternate Key XAB, the 
First Alternate Key XAB points to the Second Alternate 
Key XAB, and so on 

Output from $DISPLAY and $OPEN: 

If you want one or more key definitions, link in a suffi- 
cient number of key XABs. RMS-11 sets the appropriate 
fields to the values established when the file was created. 
If there is more than one, the Key XABs must be: 

• linked in ascending order by REF field, but not necessar- 
ily densely; for example, if you only want descriptions 
of the Second and Fourth Alternate Keys, you must link 
only the XABs for those keys, in that order 

• adjoining in the XAB chain; that is, the first Key XAB 
in the chain must point to the second one, and so on 

NOTE 

Since Key XABs describe both keys and their indexes, the 
terms : 

"key described by the XAB" 
"index described by the XAB" 

are used in the following field descriptions; they both 
refer to the same XAB. The value in the REF field deter- 
mines which key/index is described. 
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Table 


5-3: Ke 


>y Extended Attribute Block Fields 


Field 


Field 


Default 


Description 


Name 


Si ze 






BLN 


IB 


N/A 


KEY XAB length 


COD 


IB 


N/A 


XAB type 


DAN 


IB 





Level area number 


DBS 


IB 





Data bucket size 


DFL 


1W 





Level fill number 


DTP 


IB 





Key data type 


DVB 


4W 





VBN of first data bucket 


FLG 


IB 





Key characteristics 


IAN 


IB 





Levels 2+ area number 


IBS 


IB 





Index bucket size 


IFL 


1W 





Levels 2+ fill number 


KNM 


1W 





Pointer to key name 


LAN 


IB 





Level 1 area number 


LVL 


IB 





Index level of root 


MRL 


IB 





Minimum length record size 


NSG 


IB 





Number of key segments 


NUL 


IB 





Null key value 


NXT 


1W 





Next XAB 


POS 


8W 





Key position(s) in record 


REF 


IB 





Key described by XAB 


RVB 


2W 





VBN of index root 


SIZ 


8W 





Size(s) of key segments 


TKS 


IB 





Total key size 
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************* 

* * 

* BLN * 

* * 
************* 



5.3.1 B LN 

The XAB$B macro sets the one-byte Block Length (BLN) field to the Ex- 
tended Attribute Block length. 

CAUTION 
DO NOT CHANGE THE BLN FIELD. 



5.3.1.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the BLN field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ER$BLN error code. 
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************* 

* * 

* COD * 

* * 
************* 



5.3.2 COD 

The XAB$B macro sets the one-byte Code (COD) field to the Extended At- 
tribute Block type, with the symbolic value of XB$KEY. 

CAUTION 
DO NOT CHANGE THE COD FIELD. 



5.3.2.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the COD field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ER$COD error code. 
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************* 

* * 

* DAN * 

* * 
************* 



5.3.3 DAN 

The one-byte Data Area Number (DAN) field contains the number of the 
file area in which Level 0* of the index described by this XAB is (or 
will be) stored. 



5.3.3.1 Use 
Input to: 

$CREATE 

• If you are not creating a multi-area file**, that is, no 
or one Allocation XAB, ensure that the DAN field is zero 
(the default) . 

• If you are creating a multi-area file, that is, there are 
multiple Allocation XABs also linked to the FAB, set the 
DAN field to the number of the area in which you want the 
data level of this index (set by REF field) stored. This 
number must be the same as the AID field of one of the 



Allocation XABs. 



Output from: 



$DISPLAY/$OPEN 

RMS-11 sets the DAN field equal to the number of the area in 
which Level of the index indicated by the REF field is 
stored . 



5.3.3.2 Input Values 

MINIMUM = 0, meaning Area 0** 

MAXIMUM = 254, meaning the maximum possible area that may be 

allocated; however, the maximum within each program 
is restricted to the highest number in an Allocation 
XAB AID field 



*The data level (Level 0) of the Primary index contains your data re- 
cords while Level of Alternate indexes contain Secondary Index Data 
Records that point into the Primary index Level 0. See the RMS-11 
User' s Guide. 

**If there are no Allocation XABs, the entire file is in Area 0. 
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A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.3.3.3 Initialization and Default - Macro takes the form: 

X$DAN numeric 
If there is no initialization macro, DAN = 0. 
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************* 

* * 

* DBS * 

* * 
************* 



5.3.4 DBS 



The one-byte Data Bucket Size (DBS) field contains the number of 
blocks in a bucket in the file area that contains Level of the index 
described by this XAB. 



5.3.4.1 Use 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the DBS field equal to the bucket size of the 
area established for Level of this index when the file was 
created . 



5.3.4.2 Output Values 

MINIMUM = 1 

MAXIMUM = number of blocks allowed by the operating system 
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************* 

* * 

* DFL * 

* * 
************* 



5.3.5 DFL 

The one-word Data Bucket Fill Number (DFL) contains the number of 
bytes in each bucket of this index's Level that should be used to 
store data if the RAB ROP field contain RB$LOA when the Record Access 
Stream is set up ($CONNECT); if RB$LOA is not set, RMS-11 ignores the 
fill number. See the RMS-11 User's Guide for a discussion of fill 
numbers. 



5.3.5.1 Use 

Input to: 

$CREATE 

You set the DFL field equal to the number of bytes you want 
filled in each Level bucket when RMS-11 is honoring fill 
numbers. 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the DFL field equal to fill number established 
for Level of the index designated by the REF field when 
the file was created. 



5.3.5.2 Input Values 

MINIMUM = 0, meaning the buckets should be completely filled regard- 
less of value in RAB ROP field 

= half of the bytes in the bucket; this is a logical minimum, 
meaning you can specify less, but RMS-11 ignores it, supply- 
ing its own 50% figure 

MAXIMUM = total number of bytes in a bucket less one record (including 
overhead); this is a logical maximum; the physical maximum 
(total number of bytes in a bucket) can be achieved by spec- 
ifying zero 

You can figure the number of bytes in a bucket as follows: 

NRBKT ■ 512*BKS 

where BKS is the bucket size, expressed in blocks. 
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A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.3.5.3 Initialization and Default - Macro takes the form: 

X$DFL numeric 
If there is no initialization macro, DFL = 0. 



Key XAB: DFL 5-35 



************* 

* * 

* dtp * 

* * 
************* 



5.3.6 DTP 

The one-word Key Data Type (DTP) field contains a bit string indicat- 
ing the data type of the key described by this XAB. 

CAUTION 

If you are currently using RMS-11K VI. 5 and want to use the 
DTP field, you must reassemble your program using the 
RMS-11K VI. 8 RMSLIB.MLB. 



5.3.6.1 Use 

Input to: 

$CREATE 

You set the DTP field to indicate the data type of the key 
you have defined with the POS and SIZ field. 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the DTP field to indicate the data type esta- 
blished for the key indicated by the REF field when the file 
was created. 



5.3.6.2 Input Values - The DTP field must contain one of the follow- 
ing symbolic values: 

XB$BN2 Each 16-bit unsigned binary key requires two bytes. 

XB$BN4 Each 32-bit unsigned binary key requires four bytes. 

XB$IN2 Each 15-bit signed integer key requires two bytes. 

XB$IN4 Each 31-bit signed integer key requires four bytes. 

XB$PAC A packed decimal key has two decimal digits stored in 
each byte. 

XB$STG Each character of a string key is stored as a binary 
value . 

A value can be set in the field with the initialization macro shown 
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below or with the $SET field access macro (see Chapter 7). 

5.3.6.3 Initialization and Default - Macro takes the form: 

X$DTP symbolic 
If there is no initialization macro, DTP = XB$STG. 
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************* 

* * 

* DVB * 

* * 
************* 



5.3.7 DVB 

The two-word Data Virtual Block Number (DVB) field specifies the 
number of the file's virtual block that contains the first block of 
the first* bucket in Level of the index described by this XAB. 



5.3.7.1 Use 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the DVB field equal to the number of the virtual 
block containing the first data from this index in the file. 



5.3.7.2 Output Values 

MINIMUM = first data block in the file (after the Prologue) if the 
index is Primary 

MAXIMUM = last block in the file 



*Based on physical ordering from the beginning of the file. 
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************* 

* * 

* FLG * 

************* 



5.3.8 FLG 

The one-word Flags (FLG) field contains a bit string indicating char- 
acteristics of the key described by the XAB. 



5.3.8.1 Use 

Input to: 

$CREATE 

You set the FLG field to indicate the characteristics you 
want associated with the key described by the REF field. 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the FLG field to indicate the key characteris- 
tics established when the file was created. 



5.3.8.2 Input Values - The FLG field may contain one or more of the 
following symbolic values: 

XB$CHG the value in the key field described by this XAB may be 
changed during an update operation; valid only for Al- 
ternate Keys (REF field greater than 0) and in conjunc- 
tion with XB$DUP 

XB$DUP more than one record within the file may have the same 
value in the key field described by this XAB 

XB$NUL if the string key described by this XAB is completely 
filled with the character in the NULL field or the in- 
teger, binary, or packed decimal key is zero, RMS-11 
makes no entry in the index for the record; valid for 
Alternate Keys only 
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RMS-11 restricts the combination of XB$CHG and XB$DUP as follows: 

Combination 



Key Type 


XB$CHG 

+ 
XB$DUP 


XB$CHG 

+ 
Default 


Default 

+ 
XB$DUP 


Default 

+ 
Default 


Primary 


Error 


Error 


Allowed 


Allowed 


Alternate 


Allowed 


Error 


Allowed 


Allowed 



A value can be set in the field with the initialization macro shown 
below or with the $SET field access macro (see Chapter 7). 



5.3.8.3 Initialization and Default - Macro takes the form: 
X$FLG symbol ic [ I symbol ic [ ! symbol ic] ] 

If there is no initialization macro, FLG = 0, meaning: 

• For Primary Key, duplicate keys are not allowed. 

• For Alternate Keys 

— duplicate keys allowed 

— key values may change during update operation 

— no null key value 

5.3.8.4 Comments 

• At all times, for Primary Keys: 

— key values cannot change during update operation 

— no null key values 

• Since the FLG field is a bit string, values cannot be added to the 
field with the $ST0RE field access macro. You should use the $SET 
field access macro (see Chapter 7). However, you use the $ST0RE 
macro to (re) set all bits in the field. 
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************* 

* * 

* IAN * 

* * 
************* 



5.3.9 IAN 

The one-byte Index Area Number (IAN) field contains the number of the 
file area in which Levels 2+ of the index described by this XAB are 
(or will be) stored. 



5.3.9.1 Use 
Input to: 

$CREATE 

• If you are not creating a multi-area file*, that is, no 
or one Allocation XAB, ensure that the IAN field is zero 
(the default) . 

• If you are creating a multi-area file, that is, there are 
multiple Allocation XABs also linked to the FAB, set the 
IAN field to the number of the area in which you want the 
index levels two and up of this index (set by REF field) 
stored. This number must be the same as the AID field of 
one of the Allocation XABs. 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the IAN field equal to the area in which Levels 
2+ of the index indicated by the REF field are stored. 



5.3.9.2 Input Values 

MINIMUM = 0, meaning Area 0* 

MAXIMUM = 254, meaning the maximum possible area that may be 

allocated; however, the maximum within each program is 
restricted to the highest number in an Allocation XAB 
AID field 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



*If there are no Allocation XABs, the entire file is 



in Area 0. 
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5.3.9.3 Initialization and Default - Macro takes the form: 

X$IAN numeric 
If there is no initialization macro, IAN = 0. 
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************* 

* * 

* IBS * 

* * 
************* 



5.3.10 IBS 

The one-byte Index Bucket Size (IBS) field contains the number of 
blocks in a bucket in the one or two file areas that contain Levels 1+ 
of the index described by this XAB. 



5.3.10.1 Use 

Output from: 

$DISPLAY/$OPEN 

RMS--11 sets the IBS field equal to the bucket size of the 
area(s) established for Levels 1+ of this index when the 
file was created. 



5.3.10.2 Output Values 

MINIMUM = 1 

MAXIMUM = number of blocks allowed by the operating system 
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************* 

* * 

* IFL * 

* * 
************* 



5.3.11 IFL 

The one-word Index Bucket Fill Number (IFL) contains the number of 
bytes in each bucket of this index's Levels 1+ that should be used to 
store index information if the RAB ROP field contains RB$LOA when the 
Record Access Stream is set up ($CONNECT); if RB$LOA is not set, 
RMS-11 ignores the fill number. See the RMS-11 User's Guide for a 
discussion of fill numbers. 



5.3.11.1 Use 

Input to: 

$CREATE 

You set the IFL field equal to the number of bytes you want 
filled in each Levels 1+ bucket when RMS-11 is honoring fill 
numbers. 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the IFL field equal to fill number established 
for Levels 1+ of the index designated by the REF field when 
the file was created. 



5.3.11.2 Input Values 

MINIMUM = 0, meaning the buckets should be completely filled regard- 
less of the value in the RAB ROP field 

= half of the bytes in the bucket; this is a logical minimum, 
meaning you can specify less, but RMS-11 ignores it, supply- 
ing its own 50% figure 

MAXIMUM = total number of bytes in a bucket less one record (including 
overhead); this is a logical maximum; the physical maximum 
(total number of bytes in a bucket) can be achieved by spec- 
ifying zero 

You can figure the number of bytes in a bucket as follows: 

NRBKT = 512*BKS 

where BKS is the bucket size, expressed in blocks. 
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A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.3.11.3 Initialization and Default - Macro takes the form: 

X$IFL numeric 
If there is no initialization macro, IFL = 0. 
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************* 

* * 

* KNM * 

* * 
************* 



5.3.12 KNM 

The one-word Key Name Address (KNM) field points to an ASCII string 
that is associated with the key described by this XAB. RMS-11 does 
not use this field for processing, but does store it in the file Pro- 
logue during a create operation and outputs it during $DISPLAY and 
$OPEN. The RMSDSP utility also prints out this string (see the RMS-11 
User" s Guide) . 



5.3.12.1 Use 

Input to: 

$CREATE 

If you want to associate a name or other identification with 
the key described by this XAB, set the KNM field equal to 
the address of that name. 

$DISPLAY/$OPEN 

• If you do not want to provide a 32-byte buffer to hold 
the key name string, you set the KNM field to zero; 
RMS-11 does not output the key name. 

• If you are providing a buffer for the key name string, 
you set the KNM field equal to the buffer's address. 



5.3.12.2 Input Values - The KNM field must contain either: 

• zero (0) = no ASCII key name string 

• address of an ASCII string; RMS-11 reads and writes 32 bytes 
starting with this location: 

— during $CREATE, be sure that you have valid data (if only 
blanks) for that length 

— during $DISPLAY and $OPEN, be sure that the indicated buffer is 
at least 32 bytes long or the key name will overlay other data 
or instructions 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 
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5.3.12.3 Initialization and Default - Macro takes the form: 

X$KNM label 
If there is no initialization macro, KNM = 0. 
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************* 

* * 

* LAN * 

* * 
************* 



5.3.13 LAN 

The one-byte Lowest Index Level Area Number (LAN) field contains the 
number of the file area in which Level 1 of the index described by 
this XAB is (or will be) stored. 



5.3.13.1 Use 
Input to: 

$CREATE 

• If you are not creating a multi-area file*, that is, no 
or one Allocation XAB, ensure that the LAN field is zero 
(the default) . 

• If you are creating a multi-area file, that is, there are 
multiple Allocation XABs also linked to the FAB, set the 
LAN field to the number of the area in which you want the 
index level one of this index (set by REF field) stored. 
This number must be the same as the AID field of one of 
the allocation XABs. 



Output from: 



$DISPLAY/$OPEN 

RMS-11 sets the LAN field equal to the area in which 
Level 1 of the index indicated by the REF field is 
stored . 



5.3.13.2 Input Values 

MINIMUM = 0, meaning the same area as the rest of the index (Levels 
2+) , not necessarily Area 

= 1, lowest area number that can be specifically identified 

MAXIMUM = 254, meaning the maximum possible areas that may be allocat- 
ed; however, the maximum within each program is res- 
tricted to the highest number in an Allocation XAB AID 
field 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 
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■MMI 



5.3.13.3 Initialization and Default - Macro takes the form: 

X$LAN numeric 
If there is no initialization macro, LAN = 0. 



5.3.13.4 Comments - The bucket size for the area containing Level 1 
of an index must be the same as the bucket size for the area contain- 
ing the rest of the index (Levels 2+) . 
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************* 

* * 

* LVL * 

* * 
************* 



5.3.14 LVL 

The one-byte Root Level (LVL) field contains the level number of the 
Root bucket of the index described by this XAB. This number is one 
less than the depth of the index. 



5.3.14.1 Use 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the LVL field equal to the number of the index 
level of the Root bucket for the index identified by the REF 
field. 



5.3.14.2 Input Values 

MINIMUM = 1, meaning that the index is the shallowest possible, with 
one level of data and one level of index, the Root 

MAXIMUM = no logical limit 
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************* 

* * 

* MRL * 

* * 
************* 



5.3.15 MRL 

The one-word Minimum Record Length (MRL) field contains the length, in 
bytes, that a record must be to include the key described by the XAB. 



5. 3. 15. 1 Use 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the MRL field to the number of bytes in the 
shortest record that can contain the key identified by the 
REF field. 



2 Output Values - The value in the MRL field is based on the 
key's position (specified by the POS field) and the key's length (in- 
dicated by the SIZ field) . In a single-segment key, the sum of the 
two provides the minimum record length. However, in a multi-segment 
key, the pertinent segment is the one farthest from the beginning of 
the record. The starting position of that segment, plus its length, 
determine the minimum length record. 



5.3.15.3 Comments 

• If the index described by the XAB is the Primary index, then no re- 
cord smaller than the MRL value can be written to the file; RMS-11 
returns error code ER$RSZ. 

• If the index described by the XAB is an Alternate index, then if 
the record is shorter than the MRL, RMS-11 makes no entry in the 
index for the record. 
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************* 

* * 

* NSG * 

* * 
************* 



5.3.16 NSG 

The one-byte Number of Key Segments (NSG) field contains the number of 
segments specified in the key described by the XAB when the file was 
created. The POS and SIZ fields contain this number of values. 



5.3.16.1 Use 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the NSG field equal to the number of positions 
and lengths it finds in the POS and SIZ fields. 



5.3.16.2 Input Values 

MINIMUM = 1 

MAXIMUM = 8 

Only string keys will have NSG values greater than 1. 
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************* 

* * 

* NUL * 

* * 
************* 



5.3.17 NUL 

The one-byte Null Key Character (NUL) field contains the binary repre- 
sentation of the null key character for the key described by this XAB. 
This field is valid for string Alternate Keys only (REF field greater 
than 0). See the RMS-11 User's Guide for a discussion of null key va- 
lues. 



5.3.17.1 Use 

Input to: 

$CREATE 

You set the NUL field equal to the character or code you 
want used as the null key character for this key; you 
should also put the symbolic value XB$NUL in the FLG field. 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the NUL field equal to the null key value esta- 
blished when the file was created. 



5.3.17.2 Input Values - RMS-11 uses the NUL field only if the FLG 
field contains XB$NUL and the key is a string data type; if both are 
true, the NUL field must contain* a binary number whose octal value 
ranges from 000 to 377. You may represent an ASCII character (via the 
MACRO-11 single-quote (') convention) or a non-ASCII octal value. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.3.17.3 Initialization and Default - Macro takes the form: 

X$NUL value 
where value is a valid MACRO-11 representation of a one-byte value. 
If there is no initialization macro, NUL = 0. 



*If one of these conditions is false, the NUL may contain any value; 
the recommended value in that case is the default, zero. 
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5.3.17.4 Examples 

• The following code specifies a null key value of Z for a string 
key: 

KEYDEF: XAB$B XB$KEY 

X$DTP XB$STG 

X$FLG XB$NUL 
X$NUL "Z 

XAB$E 



• 



• 



The following code specifies the null key feature for a string key, 
but the null key value is the ASCII character DEL: 

KEYDEF: XAB$B XB$KEY 

X$DTP XB$STG 

X$FLG XB$NUL 
X$NUL "177 

XAB$E 

The following code specifies the null key feature for a packed de- 
cimal key; however, no null key value is necessary: 

KEYDEF: XAB$B XB$KEY 

X$DTP XB$PAC 

X$FLG XB$NUL 

XAB$E 
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************* 

* * 

* nxt * 

* * 
************* 



5.3.18 NXT 

The one-word Next XAB (NXT) field, if not zero, points to another sep- 
arately allocated XAB and thereby indicates to RMS-11 that there is at 
least one more XAB in the chain connected to the FAB via the FAB XAB 
field. See "Linking and Ordering XABs" at the beginning of this 
chapter . 



5.3.18.1 Use 
Input to: 

$CREATE/$DELETE/$EXTEND/$OPEN 

• If you have allocated another XAB and want RMS-11 to use 
it, you set the NXT field equal to the address of that 
XAB. 

• If you have not allocated an XAB and/or you want the XAB 
chain to end here, set the NXT field equal to zero; 
otherwise, RMS-11 interprets the value in the field as an 
address and tries to use the area indicated as an XAB: 
if that area is not a valid XAB, RMS-11 returns the error 
code ER$XAB. 



5.3.18.2 Input Values - The NXT field must contain either: 

• zero (0) = there are no more XABs in this chain 

• address of an Extended Attribute Block separately allocated in the 
program 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.3.18.3 Initialization and Default - Macro takes the form: 

X$NXT label 
If there is no initialization macro, NXT = 0. 
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************* 

* * 

* POS * 

* * 

************* 



5.3.19 POS 

The eight-word Key Position (POS) field contains the starting posi- 
tions within the record for all segments of the key described by this 
XAB. Combined with the SIZ and DTP fields, the POS field completely 
defines the key. 

An RMS-11 key string may contain from one to eight segments; all 
other key types require a single segment. Each word in the POS field 
specifies the starting position of a segment: the first word, the 
first segment, the second word, the second segment, and so on. Each 
segment must be contiguous, but the segments do not have to be contig- 
uous with each other. When processing records, RMS-11 combines the 
individual segments and treats them as a single, logically contiguous 
string beginning with the first segment and ending with the last. See 
also the RMS-11 User's Guide discussion of segmented keys. 



5.3.19.1 Use 

Input to: 

$CREATE 

You set the POS field to include the starting position of 
each segment in the key described by this XAB. See "Com- 
ments" for $STORE syntax. 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the POS field to include starting positions of 
the key segments established when the file was created. 



5.3.19.2 Input Values - The POS field must contain at least one num- 
eric value in the range: 

MINIMUM = 0, meaning the segment starts in the first byte of the re- 
cord 

MAXIMUM = 65535, meaning the segment starts in the last byte of the 

largest possible record 

If a string key has multiple segments, you must specify a starting po- 
sition for each segment, each within the above range, using the form: 

<seg0,segl [,seg2, . . . ,seg7] > 
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The values do not have to represent ascending byte positions in the 
record. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see "Comments" below and 
Chapter 7 ) . 



5.3.19.3 Initialization and Default - Macro takes the form: 
X$POS [<] numeric [, numeric, ... >] 

If there is no initialization macro, POS = 0. 

5.3.19.4 Comments 

• You may store or fetch the position of an individual segment in the 
POS field, by using the term 

POSn 

where n is an integer in the range to 7, indicating the segment 
number whose position you want to affect. 

Example You want to check the starting position of the third seg- 
ment of a key string: 

$FETCH R0,POS2,R4 

You want to reset the starting position of the first seg- 
ment of a key string: 

$STORE R0,POS0,R4 

In both cases, R0 is used as a buffer for the position 
number. 
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************* 

* * 

* REF * 

* * 

************* 



5.3.20 REF 

The one-byte Key of Reference (REF) field identifies the index and key 
described by this XAB. 



5.3.20.1 Use 

Input to: 

$CREATE/$EXTEND 

You set the REF field to tell RMS-11 exactly what key and 
index you are describing in the XAB. 

$DISPLAY/$OPEN 

You set the REF field to tell RMS-11 exactly what key and 
index you want RMS-11 to describe in the XAB. 



5.3.20.2 Input Values 

MINIMUM = 0, meaning Primary Key 

MAXIMUM = 254 

All values from 1 to 254 indicate Alternate Keys, first, second, and 
so on. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.3.20.3 Initialization and Default - Macro takes the form: 

X$REF numeric 
If there is no initialization macro, REF = 0. 
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************* 

* * 

* RVB * 

* * 

************* 



5.3.21 RVB 

The two-word Root Virtual Block Number (RVB) field specifies the 
number of the file's virtual block that contains the Root of the index 
represented by this XAB. 



5.3.21.1 Use 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the RVB field equal to the number of the first 
virtual block of the Root bucket for the index indicated by 
the REF field. 



5.3.21.2 Output Values - 

MINIMUM = first data block of the file, after the Prologue 

MAXIMUM = last block of the file 

A value can be set. in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 
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************* 

* * 

* SIZ * 

* * 

************* 



5.3.22 SIZ 

The eight-byte Key Size (SIZ) field contains the lengths, in bytes, of 
all segments of the key described by this XAB. Each byte in the SIZ 
field specifies the size of a segment: the first byte, the first seg- 
ment, second byte, the second segment, and so on. There must be a 
length specified for each segment given a starting position in the POS 
field. 



5.3.22.1 Use 

Input to: 

$CREATE 

You set the SIZ field to include the length of each segment 
in the key described by this XAB. See "Comments" for $STORE 
syntax . 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the. SIZ field to include lengths of the key seg- 
ments established when the file was created. 



5.3.22.2 Input Values - The SIZ field must contain at least one num- 
eric value which depends on key data type (specified by the DTP field 
in this XAB), as follows: 

15-bit Signed Integer Key Type, SIZ = or 2 

31-bit Signed Integer Key Type, SIZ = or 4 

16-bit Unsigned Binary Key Type, SIZ = or 2 

32-bit Unsigned Binary Key Type, SIZ = or 4 

String Key Type 

MINIMUM = (null segment) 

MAXIMUM = 255 



^^^lk 
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If a string key has multiple segments, you must specify a length 
for each segment, using the form: 

<lenO,lenl [,len3, . . . ,len7]> 

The sum of the multiple lengths cannot exceed 255. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.3.22.3 Initialization and Default - Macro takes the form: 
X$SIZ [<] numeric [, numeric, ... >] 

If there is no initialization macro, SIZ = 0. 

5.3.22.4 Examples 

• The following code specifies a single-segment key eight bytes long: 
KEYDEF: XAB$B XB$KEY 

X$SIZ 8. 

XAB$E 

• The following code specifies a key with four segments, defining 
their sizes and positions: 

KEYDEF: XAB$B XB$KEY 

X$SIZ <8,2,5,32> 
X$POS <19,0,13,28> 

XAB$E 



5.3.22.5 Comments - You may store or fetch the length of an individu- 
al segment in the SIZ field, by using the term 

SIZn 

where n is an integer in the range to 7, indicating the segment 
number whose length you want to affect. 
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Example You want to check the length of the third segment of a key 
string : 

$FETCH R0,SIZ2,R4 

You want to reset the length of the first segment of a key 
string: 

$STORE R0,SIZ0,R4 

In both cases, RO is used as a buffer for the length. 
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************* 

* * 

* TKS * 

* * 

************* 



5.3.23 TKS 

The one-byte Total Key Size (TKS) field specifies the number of bytes 
contained in all segments of the key described by the XAB. 



5.3.23.1 Use 

Output from; 

$DISPLAY/$OPEN 

RMS-11 sets the TKS field equal to the sum of the segment 
lengths established via the SIZ field for the key indicated 
by the REF field. 



5.3.23.2 Input Values 
MINIMUM = 1 
MAXIMUM = 255 
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5.4 Protection Extended Attribute Block 



The Protection XAB describes the protection code of a file, including 
specifications for the owner's account number. You use a Protection 
XAB generally when you do not want the default protection value for 
the operating system applied to the file. 



Protection XABs are used as: 

Input to $CREATE and $CLOSE 

For an RMS-11 file of any organization, you may set its pro- 
tection code when it is created and change that code when it 
is closed. 

Output from $DISPLAY and $OPEN 

RMS-11 supplies the current protection value for the file. 



Table 5-4: Protection Extended Attribute Block Fields 



Field 


Field 


Default 


Description 




Name 


Si ze 








BLN 


IB 


N/A 


PRO XAB length 




COD 


IB 


N/A 


XAB type 




NXT 


1W 





Next XAB 




PRG 


1W 





Programmer part 


of account number 


PRJ 


1W 





Project part of 


account number 


PRO 


1W 





File protection 


value 
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************* 

* * 

* BLN * 

* * 
************* 



5.4.1 BLN 

The XAB$B macro sets the one-byte Block Length (BLN) field to the Ex- 
tended Attribute Block length. 

CAUTION 
DO NOT CHANGE THE BLN FIELD. 



5.4.1.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the BLN field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ER$BLN error code. 
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************* 

* * 

* COD * 

* * 

************* 



5.4.2 COD 



The XAB$B macro sets the one-byte Code (COD) field to the Extended At- 
tribute Block type, with the symbolic value of XB$PRO. 



CAUTION 
DO NOT CHANGE THE COD FIELD. 



5.4.2.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the COD field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ER$COD error code. 
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************* 

* * 

* NXT * 

* * 
************* 



5.4.3 NXT 



The one-word Next XAB (NXT) field, if not zero, points to another sep- 
arately allocated XAB and thereby indicates to RMS-11 that there is at 
least one more XAB in the chain connected to the FAB via the FAB XAB 
field. See Chapter 1 at the beginning of this chapter. 



5.4.3.1 Use 
Input to: 

$CREATE/$DELETE/$EXTEND/$OPEN 



If you have allocated another XAB and want RMS-11 to use 
it, you set the NXT field equal to the address of that 
XAB. 

If you have not allocated an XAB and/or you want the XAB 
chain to end here, set the NXT field equal to zero; 
otherwise, RMS-11 interprets the value in the field as an 
address and tries to use the area indicated as an XAB: 
if that area is not a valid XAB, RMS-11 returns the error 
code ER$XAB. 



5.4.3.2 Input Values - The NXT field must contain either: 

• zero (0) == there are no more XABs in this chain 

• address of an Extended Attribute Block separately allocated in the 
program 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 

5.4.3.3 Initialization and Default - Macro takes the form: 
X$NXT label 

If there is no initialization macro, NXT = 0. 
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************* 

* * 

* prg * 

* * 
************* 



5.4.4 PRG 

The one-word Programmer Number (PRG) field contains the second number 
in the file owner's account number pair. 



5.4.4.1 Use 

Input to: 

$CLOSE/$CREATE 

You set the PRG field to the individually unique number of 
the owner of the file. 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the PRG field to the individually unique number 
of the file owner it reads from the file directory. 



5.4.4.2 Input Values 

MINIMUM = 0, meaning the default programmer number, based on the ac- 
count in which the program is currently running 

= 1, the smallest programmer number you can identify 

MAXIMUM = 255 

The programmer number specified in the Protection XAB must agree with 
the programmer number specified in the filespec indicated by the FAB 
FNA field or in the default name string indicated by the FAB DNA 
field. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.4.4.3 Initialization and Default - Macro takes the form: 

X$PRG numeric 
If there is no initialization macro, PRG = 0. 
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************* 

* * 

* PRJ * 

* * 

************* 



5.4.5 PRJ 

The one-word Project Number (PRJ) field contains the first number in 
the file owner's account number pair. 



5.4.5.1 Use 

Input to: 

$CLOSE/$CREATE 

You set the PRJ field to the group or project number of the 
owner of the file. 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the PRJ field to the group or project number of 
the file owner it reads from the file header. 



5.4.5.2 Input Values 

MINIMUM = 0, meaning the default project number, based on the account 
in which the' program is currently running 

= 1, the smallest project number you can identify 

MAXIMUM =2 55 

The project number specified in the Protection XAB must agree with the 
project number specified in the filespec indicated by the FAB FNA 
field or in the default name string indicated by the FAB DNA field. 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.4.5.3 Initialization and Default - Macro takes the form: 

X$PRJ numeric 
If there is no initialization macro, PRJ = 0. 
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************* 

* * 

* PRO * 

* * 

************* 



5.4.6 PRO 

The one-word System File Protection Code (PRO) field contains the sys- 
tem-specific code that indicates the access relationship allowed for 
the file represented by the FAB linked to this XAB. 



5. 4. 6. 1 Use 

Input to: 

$CREATE 

You set the PRO field to the protection code that controls 
access to the file as you want it. 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the PRO field equal to the protection code found 
in the file directory. 



5.4.6.2 Input Values - Specific protection values depend on operating 
system standards: 

• IAS/RSX-11M 

The file protection value identifies the file access privileges of 
four classes of users: 

group those accounts with the project number contained in 
the PRJ field of this XAB 

owner that account with the project and programmer numbers 
contained in this XAB 

system privileged accounts 

world all accounts not in the other categories 

The PRO field assumes the following format: 

1 

5 8 



I WORLD | GROUP I OWNER | SYSTEM | 



5-70 Protection XAB: PRO 



Each of the categories is allocated four bits, with the following 
meanings with respect to file access: 

bit 3 2 10 

I DELETE | EXTEND | WRITE I READ | 



If a bit is not. set (zero), the respective type of access to the 
file is allowed; if the bit is set (one) , that type of access is 
denied . 

You should use a numeric value for that PRO field that sets the ap- 
propriate bits; this number may be decimal, octal, or binary, 
though using the MACRO-11 octal radix unary operator makes it ea- 
sier . 

• RSTS/E 

The file protection value identifies the file access privileges of 
three classes of users: 

group those accounts with the project number contained in 
the PRJ field of this XAB 

owner that account with the project and programmer numbers 
contained in this XAB 

others all accounts not in the owner or group categories 

The value of the PRO field is the numeric sum of one or more of the 
following codes: 

1 read protect against owner 

2 write protect against owner 

4 read protect against everyone in group except owner 

8 write protect against everyone in group except owner 

16 read protect against others 

32 write protect against others 

See also your operating system documentation about protection codes. 

A value can be set in the field with the initialization macro shown 
below or with the $ST0RE field access macro (see Chapter 7). 



5.4.6.3 Initialization and Default - Macro takes the form: 

X$PR0 numeric 
If there is no initialization macro, PRO = 0. 
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5.5 Summary Extended Attribute Block 

The Summary XAB generally describes an Indexed file, including the 
number of keys and areas established for the file when it was created. 
Summary XABs may also be used for Relative files if you want to deter- 
mine their prologue version number. 



Summary XABs 
tions. 



are used as output only during $DISPLAY and $OPEN opera- 



Example You want to open an Indexed file, but you don't know any- 
thing about its keys or areas, including their number. You 
therefore do not know how many Key or Allocation XABs to 
link to the FAB before you issue the $OPEN macro. You can, 
however, link a Summary XAB to the FAB and initiate an open 
operation. You then examine the NOA and NOK fields of the 
Summary XAB to determine how many of the other XABs you need 
for a $DISPLAY macro. 



Table 


5-5: Summary Extended Attribute Block Fields 




Field 


Field 


Default 


Description 




Name 


Si ze 








BLN 


IB 


N/A 


SUM XAB length 




COD 


IB 


N/A 


XAB type 




NOA 


IB 





Number of areas 




NOK 


IB 





Number of keys 




NXT 


1W 





Next XAB 




PVN 


1W 





RMS-11 Prologue version 


number 
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************* 

* * 

* BLN * 

* * 
************* 



5.5.1 BLN 

The XAB$B macro sets the one-byte Block Length (BLN) field to the Ex- 
tended Attribute Block length. 

CAUTION 
DO NOT CHANGE THE BLN FIELD. 



5.5.1.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the BLN field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ER$BLN error code. 
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************* 

* * 

* COD * 

* * 

************* 



5.5.2 COD 

The XAB$B macro sets the one-byte Code (COD) field to the Extended At- 
tribute Block type, with the symbolic value of XB$SUM. 

CAUTION 
DO NOT CHANGE THE COD FIELD. 



5.5.2.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the COD field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ER$COD error code. 
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************* 

* * 

* NOA * 

* * 

************* 



5.5.3 NOA 

The one-byte Number Of Areas (NOA) field contains the number of file 
areas that were created in the file represented by the linked FAB. 



5.5.3.1 Use - The NOA field is only applicable to Indexed files. 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the NOA file equal to the number of areas in the 
file associated with the XAB. 



5.5.3.2 Output Values 
MINIMUM = 1 
MAXIMUM =2 54 
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************* 

* * 

* NOK * 

* * 

************* 



5.5.4 NOK 

The one-byte Number Of Keys (NOK) field contains the number of keys 
that were created in the file represented by the linked FAB. 



5.5.4.1 Use - The NOK field is only applicable to Indexed files. 
Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the NOK file equal to the number of keys in the 
file associated with the XAB. 

5.5.4.2 Output Values 

MINIMUM = 0, meaning a Relative file 

1, minimum number of keys for an Indexed file 
MAXIMUM = 255 
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■■pip 



************* 

* * 

* NXT * 

* * 

************* 



5.5.5 NXT 

The one-word Next XAB (NXT) field, if not zero, points to another sep- 
arately allocated XAB and thereby indicates to RMS-11 that there is at 
least one more XAB in the chain connected to the FAB via the FAB XAB 
field.. See chapter 1 at the beginning of this chapter. 



5.5.5.1 Use 
Input to: 

$CREATE/$DELETE/$EXTEND/$OPEN 

• If you have allocated another XAB and want RMS-11 to use 
it, you set the NXT field equal to the address of that 
XAB. 

• If you have not allocated an XAB and/or you want the XAB 
chain to end here, set the NXT field equal to zero; 
otherwise, RMS-11 interprets the value in the field as an 
address and tries to use the area indicated as an XAB: 
if that area is not a valid XAB, RMS-11 returns the error 
code ER$XAB. 



5.5.5.2 Input Values - The NXT field must contain either: 

• zero (0) = there are no more XABs in this chain 

• address of an Extended Attribute Block separately allocated in the 
program 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



5.5.5.3 Initialization and Default - Macro takes the form: 

X$NXT label 
If there is no initialization macro, NXT = 0. 
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************* 

* * 

* pvN * 

* * 

************* 



5.5.6 PVN 

The one-word Prologue Version Number (PVN) field contains the RMS-11 
Prologue version number. 



5.5.6.1 Use - The PVN field is only applicable to Relative and In- 
dexed files. 

Output from: 

$DISPLAY/$OPEN 

RMS-11 sets the PVN field equal to the version number it 
finds in the file Prologue, if the Summary XAB is long 
enough to contain this field (see "Comments"). 



5.5.6.2 Output Values - 

MINIMUM = 1, for Relative files and Indexed files with string keys 

MAXIMUM = 2, for Indexed files with nonstring keys 



5.5.6.3 Comments - RMS-11 fills in the PVN field if the Summary XAB 
is long enough to contain it. The XAB won't be long enough if you as- 
sembled your program using RMS-11 VI. RMSLIB.MAC and then task built 
it using RMS-11 VI. 5 RMSLIB.OLB. 
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CHAPTER 6 
NAME BLOCK 



The initialization macros (this chapter) 
(Chapter 7) are provided so that you do 
position and to a large extent, the size 
You can, therefore, treat the fields as 
possible that the positions and sizes of 
release to release of RMS-11. 



and the field access macros 
not have to know the specific 
of each field in a NAM Block, 
logical entities. It is also 
the fields will change from 



However, you can determine the position of any field in a NAM as an 
offset from the NAM'S starting address. RMS-11 represents these off- 
set values with symbols in following form: 

0$fnm 

where fnm is the three-letter name of a NAM Block field; fnm is the 
name used to reference the field in the initialization and field ac- 
cess macros. 

Example 0$ESA for the expanded string address field 

The values of these symbols can be found in the symbol table of an as- 
sembly listing file for any module containing the FAB. 



Table 6-1: NAM Block Fields 



Field 


Field 


Default 


Description 




Name 


Si ze 








DVI 


1W 





Device ID 




ESA 


1W 





Expanded string 


address 


ESL 


IB 





Expanded string 


length 


ESS 


IB 





Expanded string 


size 


FID 


IB 





File ID 





************* 

* * 

* DVI * 

* * 
************* 



6.1 DVI 

The three-word Device ID (DVI) field contains a code that the file 
processor can use in conjunction with a file ID to locate a file with- 
out consulting device directories. 



6.1.1 Use 



Input to: 

$ERASE/$OPEN 

You set the NAM DVI field equal to a device ID value RMS-11 
provided during a previous create or open by file specifica- 
tion operation. You must also set the NAM FID field equal 
to the file ID returned during the same operation as well as 
storing FB$FID in the FAB FOP field. 

Output from: 

$CREATE/$OPEN by file specification 

RMS-11 sets the DVI field equal to the code the file proces- 
sor provides during the open by file specification process. 



6.1.2 Input Values 

You should make no attempt to analyze or change the device ID provided 
by RMS-11. Store the contents of the NAM DVI field as a three-word 
quantity and supply it as such when you execute an erase or open by 
file ID operation. 
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************* 

* * 

* ESA * 

* * 

************* 



6.2 ESA 

The Expanded String Address (ESA) field contains the address of a 
buffer that you have allocated. During an open, create, or erase op- 
eration, RMS-11 places in this buffer the file specification string 
resulting from the application of default information (provided by the 
default name string of the FAB and system defaults) to the primary 
file name string of the FAB. 

The ESA buffer must be present if the FAB NAM field is not zero. 

NOTE 

The NAM ESA field and the expanded string buffer are not re- 
quired or used during an open or erase by file ID operation. 



6.2.1 Use 

Input to $CREATE/$ERASE/$OPEN: 

You set the ESA field equal to the address of a buffer where you 
want RMS-11 to store the full file specification. 



6.2.2 Input Values 

ESA must contain either: 

• zero (0) = there is no file specification buffer for this 
operation; valid only for open and erase by file ID 

• address of the first byte of a buffer for the full file specifica- 
tion; the buffer does not have to be word-aligned 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



6.2.3 Initialization and Default 
Macro takes the form: 

N$ESA address 
If there is no initialization macro, BKS = 0. 
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************* 

* * 

* ESL * 

* * 
************* 



-byte Expanded String Length (ESL) field contains the acl 
>f the full file specification RMS-11 stored beginning with 
in the NAM ESA field. 



6.3.1 Use 



Output from: 



$CREATE/$ERASE/$OPEN by file specification 

RMS-11 sets the ESL field equal to the size in bytes of the 
expanded file specification resulting from the operation. 
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************* 

* * 

* ESS * 

* * 
************* 



6.4 ESS 

The one-byte Expanded String Size (ESS) field contains the size of the 
buffer whose address you stored in the NAM ESA field. 



6.4.1 Use 



Input to: 

$CREATE/$ERASE/$OPEN 

You set the ESS field equal to the size of the buffer where 
you want RMS-11 to store the full file specification. 



6.4.2 Input Values 

MINIMUM = 1 

MAXIMUM = 255 

A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 



6.4.3 Initialization and Default 
Macro takes the form: 

N$ESS numeric 
If there is no initialization macro, ESS = 0, 
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************* 

* * 

* FID * 

* * 
************* 



6.5 FID 



The three-word File ID (FID) field contains a code that the file pro- 
cessor can use in conjunction with a device ID to locate a file with- 
out consulting device directories. 



6.5.1 Use 



Input to 



$ERASE/$OPEN 

You set the NAM FID field equal to a file ID value RMS-11 
provided during a previous create or open by file specifica- 
tion operation. You must also set the NAM DVI field equal 
to the device ID returned during the same operation as well 
as storing FB$FID in the FAB FOP field. 



Output from: 



$CREATE/$OPEN by file specification 

RMS-11 sets the FID field equal to the index the file pro- 
cessor provides during the open by file specification pro- 
cess . 



6.5.2 Input Values 

You should make no attempt to analyze or change the File ID provided 

by RMS-11. Store the contents of the NAM FID field as a three-word 

quantity and supply it as such when you execute an erase or open by 
file ID operation. 



.fl^r^^BS^L 
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CHAPTER 7 
FIELD ACCESS MACROS 



RMS-11 field access macro retrieve, modify, and test the contents of 
fields in the RMS-11 control blocks, FABs , RABs , and XABs , at run 
time. These macros enable you to treat the control block fields as 
logical entities, without regard for the placement of the fields with- 
in the control blocks and to a large degree, for the sizes of the 
fields. 

Table 7-1 contains a summary of the available macros. Each macro is 
also described in a separate section of this chapter. 

RMS-11 assumes octal radix for all numeric values used as operands for 
the field access macros. 

In all two-word fields containing numeric values, the least signifi- 
cant bits appear in the word with the lower address. 



Table 7-1: RMS-11 Field Access Macros 



Macro Name 



$COMPARE 

$FETCH 

SOPF 

$SET 

$STORE 

STESTBITS 



Field Size 



1 byte or 1 word 

Any size 

1 byte or 1 word 

1 byte or 1 word 

Any size 

1 byte or 1 word 



Function 



Compares the contents of a field 
with a value you specify. 

Copies the contents of a field into 
a location you specify. 

Resets one or more bits within a 
bit string field. 

Sets one or more bits within a bit 
string field. 

Copies the contents of a location 
you specify into a field. 

Tests one or more bits within a bit 
string field. 



************* 

* * 

* $COMPARE * 

* * 
************* 



7.1 $COMPARE 

The $COMPARE macro compares a one-byte or one-word control block data 
field with a value you specify and sets the PDP-11 condition codes. 



7.1.1 General Form 

$COMPARE source, fnm, reg 

where source represents a value you want compared with the contents of 
a control block data field. You can express this operand 
using any valid addressing mode. The operand must be 
word-aligned for comparison with one-word data fields. 

fnm is the three-letter name of a one-byte or one-word field. 
The assembler generates an error message if the name is 
invalid for the block referenced by reg or if the field 
specified by fnm is a multiword field. 

reg is a general register (RO through R5) loaded with the ad- 
dress of the control block containing the specified 
field. 



7.1.2 Effect 

The $COMPARE macro makes the syntax checks as described under "General 
Form." Then, if the source operand is #0, the macro generates a TST or j|i(k 
TSTB instruction, according to the size of the field. If the source 
operand is not #0, the macro generates a CMP or CMPB instruction ap- 
propriately, comparing the source operand with the specified field as 
an offset from the contents of the specified register. 

At run time, condition codes are set according to the instruction gen- 
erated . 



7.1.3 Examples 

• $COMPARE #SU$SUC,STS,R1 

The contents of the STS field in the control block pointed to by Rl 
are compared with the symbolic completion value SU$SUC. 
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$COMPARE 2(Rl),RSZ,R5 

The contents of the Record Size field in the RAB indicated by R5 
compared with the operand specified by indexed addressing mode. 



is 



$COMPARE #O f STS, 


Rl 


BGT 


14$ ; 




BLT 


ERRTN 




JMP 


TRUBLE , 





CONTINUE IF SUCCESSFUL 
HANDLE ERROR IF THERE IS ONE 
SOFTWARE IS IN A JAM 



General register Rl points to the block controlling the operation 
just completed (FAB for file operations, RAB for record opera- 
tions) . The program then branches according 
STS field. 



to the contents of the 
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************* 

* * 

* $FETCH * 

* * 
************* 



7.2 $FETCH 

The $FETCH macro copies the contents of a control block data field 
into a location you specify. This macro can be used to access a field 
of any size. 



7.2.1 General Form 

$FETCH destination, fnm,reg 

where destination is a location within your program where you want the 

contents of a control block field copied. The fol- 
lowing restrictions apply to this operand: 

• You cannot use immediate mode or any form of de- 
ferred addressing mode: the assembler generates 
an error. 

• If fnm is POS or SIZ, you cannot use register 
mode addressing: the assembler generates an 
error. 

• For multiword fields other than POS or SIZ, use 
register mode addressing carefully: the $FETCH 
macro uses successive registers as destination 
operands for successive words of the data field; 
it uses the register containing the control block 
address if the data field is long enough. The 
results are unpredictable. 

• For single- and multiword fields, the destination 
location must be word-aligned. 

fnm is the three-letter name of any field within the 
control block. The assembler generates an error if 
the name is invalid for the block referenced by reg. 

To reference Key XAB SIZ and POS fields, you: 

• specify SIZ or POS to fetch all eight words of 
the field. The macro copies the words into suc- 
cessive locations beginning with the destination 
you specify. 

• specify SIZ or POS plus a number from through 7 
to fetch a single word from the field. See "Ex- 
amples. " 
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reg is a general register (RO through R5) loaded with 
the address of the control block containing the 
source data field. 



7.2.2 Effect 

The $FETCH macro makes the syntax checks as described under "General 
Form." Then, the macro generates a MOVB or one or more MOV instruc- 
tions, according to size of the field. 



7.2.3 Examples 

• $FETCH R2,RBF,R4 

General register R4 contains the address of a RAB . The macro co- 
pies the contents of that RAB's RBF field into general register R2. 

• $FETCH 8. (R3) ,MRN,R1 

General register Rl contains the address of a FAB. The macro co- 
pies both words of that FAB * s MRN field into successive words be- 
ginning with the specified location. 

• SFETCH LSEG3,SIZ2,R5 

General register R5 contains the address of a Key XAB. The macro 
copies the length of the third key segment into the location la- 
beled LSEG3. 
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************* 

* * 

* $OFF * 

* * 
************* 



7.3 $OFF 

The $OFF macro resets one or more bits within a one-byte or one-word 
bit string data field. 



7.3.1 General Form 

$OFF value ,fnm, reg 

where value is an expression or location specifying the bits within 
the data field you want reset, 

fnm is the three-letter name of a one-byte or one-word field. 
The assembler generates an error message if the name is 
invalid for the block referenced by reg or if the field 
specified by fnm is a multiword field. 

reg is a general register (RO through R5) loaded with the ad- 
dress of the control block containing the specified field. 



7.3.2 Effect 

The $OFF macro makes the syntax checks as described under "General 
Form." Then, the macro generates one or more BIC or BICB instructions, 
according to size of the field. 



7.3.3 Examples 

• $OFF RB$KGE,R0P,R2 

General register R2 contains the address of a RAB. The macro oper- 
ates on that RAB's ROP field, resetting the bit that specifies gre- 
ater than or equal key match during a random record operation. 



7.3.4 Comments 

The $OFF macro resets individual bits. You should use the $STORE 
macro instead if you want to clear an entire bit string field or reset 
a value in a field not a bit string. 
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************* 

* * 

* $SET * 

* * 
************* 



7.4 $SET 

The $SET macro sets one or more bits within a one-byte or one-word bit 
string data field. 



7.4.1 General Form 

$SET value , fnm, reg 

where value is an expression or location specifying the bits within 
the data field you want set, 

fnm is the three-letter name of a one-byte or one-word field. 
The assembler generates an error message if the name is 
invalid for the block referenced by reg or if the field 
specified by fnm is a multiword field. 

reg is a general register (RO through R5) loaded with the ad- 
dress of the control block containing the specified data 
field. 



7.4.2 Effect 

The $OFF macro makes the syntax checks as described under "General 
Form." Then, the macro generates one or more BIS or BISB instructions, 
according to size of the field. 



7.4.3 Examples 

• $SET FB$GET!FB$UPD,FAC,R4 

General register R4 contains the address of a FAB. The macro sets 
bits within that FAB • s FAC field indicating get and update opera- 
tions will be performed on the associated file. The $SET macro is 
executed before a $CREATE or $OPEN operation is initiated. 

• $SET RB$E0F,R0P,R1 

General register Rl contains the address of a RAB. The macro sets 
the bit within that RAB ' s ROP field that specifies positioning to 
end-of-file during the following $CONNECT record operation. 
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7.4.4 Comments 

The $SET macro sets individual bits. You should the $STORE macro 
instead if you want to: 

• set only the specified values in a bit string field, ensuring that 
no other bits remain set 

• set a value in a field not a bit string $STORE macro. 
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************* 

* * 

* $STORE * 

* * 
************* 



7.5 $STORE 

The $STORE macro copies values from a location you specify into a con- 
trol block data field. This macro can be used to access a field of 
any size. 



7.5.1 General Form 

$STORE source, fnm,reg 

where source represents a value or series of values you want stored in 
a control block data field. The following restrictions 
apply to this operand: 

o You cannot use any form of deferred addressing mode: 
the assembler generates an error. 

o Immediate mode addressing can be used only with 
one-byte and one-word fields: the assembler generates 
an error. 

<» If fnm is POS or SIZ, you cannot use register mode ad- 
dressing: the assembler generates an error. 

9 For multiword fields other than POS or SIZ, use regis- 
ter mode addressing carefully: the $STORE macro uses 
successive registers as source operands for successive 
words of the data field; it uses the register con- 
taining the control block address if the data field is 
long enough. The results are unpredictable. 

•» For single- and multiword fields, the source location 
must be word-aligned. 

fnm is the three-letter name of any field within the control 
block. The macro changes all bytes in this field. The 
assembler generates an error if the name is invalid for 
the block referenced by reg. 

To reference Key XAB SIZ and POS fields, you: 

• specify SIZ or POS to change all eight words of the 
field. The macro copies eight words from successive 
locations beginning with the source location you spec- 
ify. 
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• specify SIZ or POS plus a number from through 7 to 
store a single word into the field. See "Examples." 

reg is a general register (RO through R5) loaded with the ad- 
dress of the control block containing the source data 
field. 



7.5.2 Effect 

The $STORE macro makes the syntax checks as described under "General 
Form." Then, the macro generates a MOVB or one or more MOV instruc- 
tions, according to size of the field. For multiword fields, the 
macro generates a MOV instruction for each word in the field, begin- 
ning with the specified source location and using successive words 
after that. 



7.5.3 Examples 

• $STORE 0,ALQ,R3 

General register R3 contains the address of a FAB. The macro 
clears that FAB ' s two-word ALQ field. 

• $STORE INPUT, FAB, Rl 

General register Rl contains the address of a RAB . The macro 
stores the address of a FAB in that RAB ' s FAB field. 

• $STORE 23.,SIZ2,R1 

General register Rl points to a Key XAB. The macro changes the 
size of the third segment of the key defined by the XAB. 
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■Hum 



************* 

* * 

* $TESTBITS * 

* * 
************* 



7.6 $TESTBITS 

The $TESTBITS macro compares one or more bits within a one-byte or 
one-word control block data field with a value you specify and sets 
the PDP-11 condition codes. 



7.6.1 General Form 

$TESTBITS value, fnm, reg 

where value is an expression or location specifying the bits within 
the data field you want tested, 

fnm is the three-letter name of a one-byte or one-word field 
within a control block. The assembler generates an error 
message if the name is invalid for the block referenced by 
reg or if the field specified by fnm is a multiword field. 

reg is a general register (RO through R5) loaded with the ad- 
dress of the control block containing the specified data 
field. 



7.6.2 Effect 

The $OFF macro makes the syntax checks as described under "General 
Form.'" Then, the macro generates one or more BIT or BITB instructions, 
according to size of the field. 



7.6.3 Examples 

$TESTBITS FB$UPD!FB$PUT,FAC,R3 

General register R3 contains the address of a FAB. The macro 
checks that FAB ' s FAC field to determine if the current program can 



issue update or p 
condition code " 



kj contains tne aaaress or a tAts. me macro 
FAC field to determine if the current program can 
ut operations. If either or both bits are set, 
is not set; if neither is set, code Z is set. 
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CHAPTER 8 
FILE AND RECORD OPERATION MACROS 



8.1 FILE OPERATION MACROS 

A file operation macro causes RMS-11 to perform an action related to 
an entire file. The macro name indicates the type of operation per- 
formed. The fields of the FAB associated with the macro in the cal- 
ling sequence identifies the file and qualifies the operation. 

Table 8-1 summarizes the RMS-11 file operation macros. 



Table 8-1: RMS-11 File Operation Macros 



Macro Name 



Description 



$CLOSE 

$CREATE 

$DISPLAY 

$ERASE 

$EXTEND 

$OPEN 



Closes an open RMS-11 file so that your program can no 
longer access its contents. 

RMS-11 creates and opens an RMS-11 file as described by 
the associated FAB and XABs, if any. 

Stores attributes of an existing RMS-11 file in FAB and 
XAB fields. 

Deletes an existing RMS-11 file and removes its entry(s) 
from a directory. 

Increases the number of blocks allocated to an RMS-11 
file. 

Opens an existing RMS-11 file, making its contents ava- 
ilable for processing. 



*************** 

* * 

* $CLOSE * 

* * 
*************** 



8.1.1 $CLOSE 

The $CLOSE macro closes an open RMS-11 file, making its contents una- 
vailable to your program. The operation effectively disconnects all 
the file's Record Access Streams; if a stream has an outstanding I/O 
request, the close fails with the ER$ACT error code. However, you 
should shut down all streams with $DISCONNECT macros before initiating 
a close operation. 



8.1.1.1 Buffer Requirements - One BDB and 512 bytes of I/O buffer 
space. 

NOTE 

Since any record operation requires at least one BDB and an 
I/O buffer a block long, the buffer requirements for this 
operation are typically met without specific attention on 
your part. 



8.1.1.2 Input Fields - 

FAB FOP (can contain FB$RWC to rewind a magtape file) 
IFI 

PRO XAB All fields 



8.1.1.3 Output Fields - 

FAB IFI (set to zero) 

BPA (address of buffer area returned for your use) 
BPS (size of buffer area returned for your use) 
STS 
STV 
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MM 



8.1.1.4 General Form - 

$CLOSE fab[, error] 

where fab is the address of a File Access Block representing an open 
RMS-11 file. 

error is the address of a completion routine to be called if the 
$CLOSE operation fails. 



8.1.1.5 Comments - 

• Even if RMS-11 returns the ER$WER error code in the FAB STS field, 
the file is closed and deaccessed. 

• If you issue a record operation on a file after it is closed, 
RMS-11 returns error code ER$ISI. 

• If your program operates as follows, be sure to detach the NAM 
Block before initiating the $CLOSE macro: RMS-11 destroys the NAM 
FID field during close. 

1. Program links NAM Block to FAB, then opens file by file specif- 
ication. 

2. Program closes file. 

3. Program opens or erases file by file ID. 
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*************** 

* * 

* $CREATE * 

* * 
*************** 



8.1.2 $CREATE 

The $CREATE macro creates an RMS-11 file with the attributes you spec- 
ify in a FAB and any XABs linked to that FAB, then makes the new files 
available for processing by your program. 

Key and Allocation XABs must be grouped in densely ascending order 
(see Section 5.0.3); otherwise, RMS-11 returns the error code ER$ORD. 
An illogical XAB type in the chain causes the ER$COD error code. 

Example Summary XAB. 

Example Key XAB for a Sequential file. 

If no Allocation XABs are linked to the FAB, the create operation cre- 
ates the file as a single area (Area 0), using data from the FAB 
fields to control its processing. 

However, if one or more Allocation XABs are linked to the FAB, the 
create operation ignores the FAB ALQ and BKS fields, creating the file 
according to the values in the ALL XAB(s), establishing areas as spec- 
ified . 

If a NAM Block is linked to the FAB, RMS-11 provides the expanded file 
specification of the new file. 

The new file must be closed before your program terminates. 



8.1.2.1 Buffer Requirements - One BDB and 512 bytes of I/O buffer 
space. 

NOTE 

Since any record operation requires at least one BDB and an 
I/O buffer a block long, the buffer requirements for this 
operation are typically met without specific attention on 
your part. 
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8.1.2.2 Input Fields - 

FAB ALQ (ignored if Allocation XABs linked) 
BKS (ignored if Allocation XABs linked) 
BLS (magnetic tape files only) 
BPA 
BPS 

DEQ (used when no ALL XABs or ALL XAB DEQ field is zero) 
DNA 
DNS 

FAC (must contain at least FB$PUT) 
FNA 
FNS 
FOP 

FSZ (VFC records only) 
LCH 

MRN (Relative files only) 
MRS 
NAM 
ORG 
RAT 
RFM 
RTV 
SHR 
XAB 

ALL XAB All fields 

KEY XAB All fields 

PRO XAB All fields 



8.1.2.3 Output Fields - 

FAB DEV 
IFI 
STS 
STV 

NAM DVI 
ESA 
ESL 
FID 



8.1.2.4 General Form - 

$CREATE rab[, error] 

where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 

error is the address of a completion routine to be called if the 
$CREATE operation fails. 
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*************** 

* * 

* $DISPLAY * 

* * 
*************** 



8.1.3 $DISPLAY 

The $DISPLAY macro causes RMS-11 to store attribute information from 
an open file in XAB fields. 

Key and Allocation XABs must be grouped in ascending order (error code 
ER$ORD) , but they do not have to be densely ordered. RMS-11 ignores 
excess and illogical XABs. 



8.1.3.1 Buffer Requirements - One BDB and 512 bytes of I/O buffer 
space. 

NOTE 

Since any record operation requires at least one BDB and an 
I/O buffer a block long, the buffer requirements for this 
operation are typically met without specific attention on 
your part. 



8.1.3.2 Input Fields - 





FAB 


IFI 
XAB 


ALL 


XAB 


AID 
NXT 


DAT 


XAB 


NXT 


KEY 


XAB 


NXT 


PRO 


XAB 


NXT 


SUM 


XAB 


NXT 
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8.1.3.3 Output Fields - 

FAB STS 
STV 

ALL XAB ALN 

ALQ (number of blocks unused in current extent) 

AOP (can contain XB$CTG) 

BKZ 

DEQ 

LOC 

DAT XAB All fields 

KEY XAB All fields 

PRO XAB All fields 

SUM XAB All fields 

NAM All fields 



8.1.3.4 General Form - 

$DISPLAY fab[, error] 

where fab is the address of a File Access Block representing an exist- 
ing RMS-11 file. 

error is the address of a completion routine to be called if the 
$DISPLAY operation fails. 



8.1.3.5 Examples - 

• A program that opens a file with unknown attributes cannot link in 
the proper Key and Allocation XABs. That program can link a Summa- 
ry XAB to the FAB, then open the file. From the SUM XAB, the pro- 
gram determines whether XABs are appropriate, then how many of each 
are necessary. The program links in the proper XABs and executes a 
$DISPLAY macro to obtain the attribute information. 

• A program has room for only one XAB. It can accumulate the infor- 
mation it needs on areas and keys by executing a series of $DISPLAY 
macros, changing the XAB fields appropriately between operations. 
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*************** 

* * 

* $ERASE * 

* * 
*************** 



8.1.4 $ERASE 

The $ERASE macro deletes an RMS-11 file and removes its directory 
entry(s) . The blocks occupied by the file are made available for 
reuse in other files. 

You can erase a file by file specification or by file ID. You indi- 
cate the file specification in a FAB. To specify a file by file ID, 
you must: 

link a NAM Block to the FAB 

indicate the correct ID with the NAM FID field 

set the value FB$FID in the FAB FOP field 

set appropriate values in the other input fields (see "Input 
Fields") 

f the file is open, your program cannot erase it on the logical chan- 
nel it was opened on. 

Example A file is opened with the FAB LCH field set to 3. Channel 3 
cannot be used for any other file operation, including 
erase, until that file is closed. 

You cannot erase magnetic tape files or files on unit record devices. 



8.1.4.1 Buffer Requirements - One BDB and 512 bytes of I/O buffer 
space. 

NOTE 

Since any record operation requires at least one BDB and an 
I/O buffer a block long, the buffer requirements for this 
operation are typically met without specific attention on 
your part. 
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8.1.4.2 Input: Fields - 

FAB BPA 
BPS 
DNA 
DNS 
FNA 
FNS 

LCH (must be different from open LCH) 
NAM 

NAM DVI 
ESS 
FID 



8.1.4.3 Output Fields - 

FAB STS 
STV 



8.1.4.4 General Form - 

$ERASE fab[, error] 

where fab is the address of a File Access Block representing an exist- 
ing RMS-11 file. 

error is the address of a completion routine to be called if the 
$ERASE operation fails. 



8.1.4.5 Comments - If your or another program has a file open and 
your program erases the file (on a different logical channel) , the 
file processor does not delete the file from the directory and release 
its allocated blocks until all accessors close the file. 
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*************** 

* * 

* $EXTEND * 

* * 
*************** 



8.1.5 $EXTEND 

The $EXTEND macro requests the file processor to add blocks to a 
file's allocation. 

If no Allocation XABs are linked to the FAB, RMS-11 extends Area 0*, 
using data from the FAB fields to control its processing. If the FAB 
FOP field contains FB$CTG, RMS-11 requests the file processor to allo- 
cate the requested blocks contiguously with those blocks already allo- 
cated to the file; if no contiguous blocks are available, RMS-11 re- 
turns an error. 

However, if one or more Allocation XABs are linked to the FAB, RMS-11 
extends the areas indicated by the ALL XAB AID fields by the amounts 
specified in the ALL XAB ALQ fields. If the XAB AOP field contains 
XB$CTG, RMS-11 requests the file processor to allocate the requested 
blocks contiguously with those blocks already allocated to the area; 
if no contiguous blocks are available, RMS-11 returns an error.} 



8.1.5.1 Buffer Requirements - One BDB and 512 bytes of I/O buffer 
space . 

NOTE 

Since any record operation requires at least one BDB and an 
I/O buffer a block long, the buffer requirements for this 
operation are typically met without specific attention on 
your part. 



8.1.5.2 Input Fields - 

FAB ALQ (ignored if Allocation XABs linked) 

FOP (can contain FB$CTG; ignored if Allocation XABs linked) 

IFI 

XAB 

ALL XAB AID 
ALQ 
AOP (can contain XB$CTG) 



JSe^^™ 



*For Sequential and Relative files, Area is the file. 
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8.1.5,3 Output Fields - 

FAB ALQ (number of blocks actually added to the file) 
STS 
STV 

ALL XAB ALQ (number of blocks actually added to the file) 



8.1.5.4 General Form - 

$EXTEND rab[, error] 

where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 

error is the address of a completion routine to be called if the 
$EXTEND operation fails. 



8.1.5,, 5 Comments - RMS-11 applies the following restrictions to the 
erase operation: 

• The file must be open. 

• All Record Access Streams connected to the file must be inactive; 
otherwise, RMS-11 returns error code ER$ACT. 

• The file must have been opened with at least one of the following 
specified in the FAB FAC field: 

FB$DEL 
FB$PUT 
FB$UPD 

• The file does not reside on magnetic tape; otherwise, RMS-11 re- 
turns error code ER$IOP. 
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*************** 

* * 

* $OPEN * 

* * 
*************** 



8.1.6 $OPEN 

The $OPEN macro makes an existing RMS-11 file available for processing 
by your program. RMS-11 also returns the basic attributes of the file 
in the FAB associated with the macro; if XABs are linked to the FAB, 
RMS-11 files in attribute information appropriately; and if a NAM 
Block is linked, RMS-11 provides the expanded file specification of 
the open file. 

Key and Allocation XABs must be grouped in ascending order (error code 
ER$ORD) , but they do not have to be densely ordered. RMS-11 ignores 
excess and illogical XABs. 

You can open a file by file specification or by file ID. You indicate 
the file specification in a FAB. To specify a file by file ID, you 
must: 

• link a NAM Block to the FAB 

• indicate the correct ID with the NAM FID field 

• set the value FB$FID in the FAB FOP field 

• set appropriate values in the other input fields (see "Input 
Fields") 



8.1.6.1 Buffer Requirements - One BDB and 512 bytes of I/O buffer 
space. 

NOTE 

Since any record operation requires at least one BDB and an 
I/O buffer a block long, the buffer requirements for this 
operation are typically met without specific attention on 
your part. 
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8.1.6.2 Input Fields - 

FAB BPA 
BPS 

DEQ (used as temporary run-time value) 
DNA 
DNS 
FAC 
FNA 
FNS 
FOP 
LCH 
NAM 
RTV 
SHR 
XAB 

ALL XAB AID 
DEQ 
NXT 

DAT XAB NXT 

PRO XAB NXT 

SUM XAB NXT 

NAM DVI 
ESS 
FID 



8.1.6.3 Output Fields - 

FAB ALQ 
BKS 

DEQ (if input value = 0, set to value set at create time) 
BLS (magnetic tape files only) 
DEV 

FOP (contains FB$CTG if the file is contiguous) 
FSZ (VFC records only) 
IFI 

MRN (Relative files only) 
MRS 
ORG 
RAT 
RFM 
RTV 
STS 
STV 

ALL XAB ALN 

ALQ (number of blocks unused in current extent) 
AOP (can contain XB$CTG) 
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BKZ 
DEQ 
LOC 

DAT XAB All fields ^^ 

PRO XAB All fields 

SUM XAB All fields 

NAM All fields 

8.1.6.4 General Form - 

$OPEN fab[, error] 

where fab is the address of a File Access Block representing an exist- 
ing file. 

error is the address of a completion routine to be called if the 
$OPEN operation fails. 



8.1.6.5 Comments - If you intend to extend the file while it is open, 
ensure that the FAB FAC field contains FB$DEL, FB$PUT, and/or FB$UPD 
before your program initiates the open operation. 
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8.2 RECORD OPERATION MACROS 

After it has created or opened an RMS-11 file, your program can per- 
form record operations on it. These operations involve the following 
concepts that are explained in the RMS-11 User's Guide and Chapter 1 
of this manual. 

Record Access Streams 

File sharing 

Context, Current Record, and Next Record 

Synchronous and asynchronous record operations 



Table 8-2: RMS-11 Record Operation Macros 



Macro Name 



$CONNECT 
$DELETE 

$DISCONNECT 

$FIND 

$FLUSH 

$FREE 

$GET 

$NXTVOL 

$PUT 

$REWIND 

$TRUNCATE 

$UPDATE 

$WAIT 



Description 



Establishes a Record Access Stream. 

Deletes a record from an RMS-11 Relative or Indexed 
file. 

Terminates a Record Access Stream. 

Locates a record in an RMS-11 file. 

Moves all data in unwritten I/O buffers to disk. 

Unlocks a bucket locked by a Record Access Stream. 

Moves a record from an RMS-11 file into your program's 
user buffer. 

Continues processing with the next volume of magnetic 
tape multivolume set. 

Moves a record from your program's user buffer to an 
RMS-11 file. 

Resets a Record Access Stream's context to the logical 
beginning of an RMS-11 file. 

Deletes record at the end of an RMS-11 Sequential 
file. 

Replaces a record in an RMS-11 file with a record from 
your program's user buffer. 

Suspends processing until an RMS-11 asynchronous re- 
cord operation completes. 
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*************** 

* * 

* $CONNECT * 

* * 
*************** 



8.2.1 $CONNECT 

The $CONNECT macro establishes a Record Access Stream by associating a 
RAB with a FAB. RMS-11 also allocates buffer space or uses the GSA 
routine you provided to allocate buffer space, for: 

• internal control structures from the central buffer pool 

• I/O buffers from the central or private pool as you indicate in the 
FAB, according to file organization and the values specified in RAB 
MBC and MBF fields 



8.2.1.1 Input RAB Fields - 

BID 

BLN 

FAB 

KRF (Indexed files only) 

MBC (disk Sequential files only) 

MBF (Relative and Indexed files only) 

ROP 

UBF (see RBF under "Output RAB Fields") 



8.2.1.2 Output RAB Fields - 

ISI 

RBF (= UBF value for Locate Mode on Sequential files) 

STS 

STV 



8.2.1.3 General Form - 

$CONNECT rab[ , error [, success] ] 

where rab is the address of a Record Access Block you want connected 
to a FAB . 

error is the address of a completion routine to be called if the 
$CONNECT operation fails. 

success is the address of a completion routine to be called if the 
$CONNECT operation succeeds. 
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*************** 

* * 

* $DELETE * 

* * 
*************** 



8.2.2 $DELETE 

The $DELETE macro deletes an existing record from a Relative or In- 
dexed file. If your program initiates a delete operation on a Sequen- 
tial file, RMS-11 returns error code ER$IOP. 

The $DELETE operation always applies to the Current Record. 
Therefore, your program must successfully execute a $FIND or $GET 
macro before initiating a $DELETE macro; otherwise, RMS-11 returns 
error code ER$CUR. 



8.2.2.1 Input RAB Fields - 

BID 
BLN 
IS I 
ROP 



8.2.2.2 Output RAB Fields - 

STS 
STV 



8.2.2.3 General Form - 

$DELETE rab[ , error [, success] ] 

where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 

error is the address of a completion routine to be called if the 
$DELETE operation fails. 

success is the address of a completion routine to be called if the 
$DELETE operation succeeds. 
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*************** 

* * 

* $DISCONNECT * 

* * 
*************** 



8.2.3 $DISCONNECT 

The $DISCONNECT macro terminates a Record Access Stream, ending the 
association between a FAB and a RAB. RMS-11 releases all buffer space 
for reuse. 



8.2.3.1 Input RAB Fields - 

BID 
BLN 
ISI 



8.2.3.2 Output RAB Fields - 

ISI (set to zero) 

STS 

STV 



8.2.3.3 General Form - 

$DISCONNECT rab [ , error [, success] ] 

where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 

error is the address of a completion routine to be called if the 
$DISCONNECT operation fails. 

success is the address of a completion routine to be called if the 
$DISCONNECT operation succeeds. 



8.2.3.4 Comments - The $DISCONNECT macro does not rewind magnetic 
tape files. If you want the file positioned to beg inning-of-f ile for 
a subsequent connect operation, use the $REWIND macro before initiat- 
ing the disconnect operation. 



,'ffl^"^^^^ 



iffrrlliH^ 
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*************** 

* * 

* $FIND * 

* * 
*************** 



8.2.4 $FIND 

The $FIND macro locates a specified record in a file and returns its 
Record's File Address in the RAB RFA field. During the operation, 
RMS-11 sets the Current Record pointer and for Sequential Access Mode 
only, the Next Record pointer. 



8.2.4.1 Input RAB Fields - 

BID 

BLN 

IS I 

KBF (Random Access Mode only) 

KRF (Random Access Mode on Indexed files only) 

KSZ (Random Access Mode only) 

RAC 

RFA (if RAC contains RB$RFA) 

ROP 



8.2.4.2 Output RAB Fields - 

BKT (Sequential Access Mode on Relative files only) 

RFA (if RAC does not contain RB$RFA) 

STS 

STV 



8.2.4.3 General Form - 

$FIND rab[ ,error[ , success] ] 

where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 

error is the address of a completion routine to be called if the 
$FIND operation fails. 

success is the address of a completion routine to be called if the 
$FIND operation succeeds. 
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8.2.4.4 Comments - 



• 



RMS-11 allows Access by RFA during find operations on disk files 
only. 

Normally, you would not use Access by RFA for find operations on 
Relative and Indexed files, since the output of the operation is 
the RFA used as input. However, a find by RFA returns error code 
ER$DEL if the specified record once existed in the file, but was 
subsequently deleted: a random find operation returns error code 
ER$RNF whether the record never existed or was deleted. 

In Sequential Access Mode, a find operation on an Indexed file uses 
the index of reference set by the most recent successful get, se- 
quential find, or connect operation. If you want to use a differ- 
ent index for sequential processing, you should execute a rewind or 
a random get operation specifying the key of reference (RAB KRF 
field) you want. 

If the file allows duplicates in the key of reference, RMS-11 does 
not indicate if the record located is one of a series containing 
duplicates in that field. 



-ilff^fl^ 
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*************** 

* * 

* $FLUSH * 

* * 

*************** 



8.2.5 $FLU"SH 

The $FLUSH macro writes all modified I/O buffers associated with a Re- 
cord Access Stream to disk, if they haven't been written. With this 
operation, you can ensure that all record activity up to a point in 
time is reflected in the file. For Relative and Indexed files, any 
bucket locked by the stream remains locked. 



8.2.5.1 Input RAB Fields - 

BID 
BLN 
IS I 



8.2.5.2 Output RAB Fields - 

STS 
STV 



8.2.5.3 General Form - 

$FLUSH rab [, error [, success] ] 

where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 

error is the address of a completion routine to be called if the 
$FLUSH operation fails. 

success is the address of a completion routine to be called if the 
$FLUSH operation succeeds. 
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*************** 

* * 

* $FREE * 

* * 
*************** 



8.2.6 $FREE 

The $FREE macro unlocks a bucket that RMS-11 locked on behalf of a Re- 
cord Access Stream. If no bucket is locked, RMS-11 returns error code 
ER$RNL. 

See Chapter 2 of the RMS-11 User's Guide for more information on file 
sharing . 



8.2.6.1 Input RAB Fields - 

BID 
BLN 
ISI 



8.2.6.2 Output RAB Fields - 

STS 
STV 



8.2.6.3 General Form - 

$FREE rab[ , error [, success] ] 

where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 

error is the address of a completion routine to be called if the 
$FREE operation fails. 

success is the address of a completion routine to be called if the 
$FREE operation succeeds. 



8.2.6.4 Comments - If you are using multiple Record Access Streams to 
access a file, you must not merely reissue a record operation that 
fails with error code ER$RLK. Since one of your program's streams can 
have the target bucket locked, you could place the program into an in- 
finite loop if you continue to issue the same operation. Therefore, 
you should execute a $FREE macro for all other streams to the same 
file. Then you can safely reinitiate the original record operation 
until RMS-11 indicates successful completion. 
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*************** 

* * 

* $GET * 

* * 
*************** 



8.2.7 $GET 

The $GET macro retrieves a record from an RMS-11 file, moving the re- 
cord from the I/O buffer to your program's user buffer* and returning 
the record's RFA in the RAB RFA field. After a successful operation, 
the RAB RBF and RSZ fields describe the retrieved record with the ad- 
dress of its first byte and its length, respectively. 



8.2.7.1 Input RAB Fields - 

BID 

BLN 

IS I 

KBF (Random Access Mode only) 

KRF (Random Access Mode on Indexed files only) 

KSZ (Random Access Mode only) 

RAC 

RFA (if RAC contains RB$RFA) 

RHB (VFC records only) 

ROP 

UBF (regardless of Record Transfer Mode) 

USZ 



8.2.7.2 Output RAB Fields - 

BKT (Sequential Access Mode on Relative files only) 

RBF 

RFA (if RAC does not contain RB$RFA) 

RSZ 

STS 
STV 



8.2.7.3 General Form - 

$GET rab[ , error [, success] ] 

where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 



*Unless you specify Locate Record Transfer Mode (RB$LOC in the RAB ROP 
field) . 
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error is the address of a completion routine to be called if the 
$GET operation fails. 

success is the address of a completion routine to be called if the 
$GET operation succeeds. 



8.2.7.4 Comments - 

• After a successful get operation from a unit record device, such as 
a terminal, the less significant byte of the RAB STV field contains 
a code representing the character that terminated the input record, 
as follows: 

Code Character 
(in octal) Represented 

15 Carriage Return 

33 Escape 

32 CTRL/Z 

other 

Except when the code is 0, the terminating character is never in 
the record described by the RAB RBF and RSZ fields. 

Example $GET /RETRIEVE A RECORD 

CMPB #0,O$STS(R5) ;CHECK IF TERMINATOR STILL IN RE- 
CORD 

• RMS-11 allows Access by RFA during get operations on disk files 
only. 

• Normally, you would not use Access by RFA for get operations on Re- 
lative and Indexed files, since the output of the operation is the 
RFA used as input. However, a get by RFA returns error code ER$DEL 
if the specified record once existed in the file, but was subse- 
quently deleted: a random get operation returns error code ER$RNF 
whether the record never existed or was deleted. 

• In Sequential Access Mode, a get operation not preceded by a suc- 
cessful find uses the index of reference set by the most recent 
successful get, find, or connect operation. If you want to use a 
different index for sequential processing, you should execute a 
rewind or a random get or find operation specifying the key of 
reference (RAB KRF field) you want. 

• If the file allows duplicates in the key of reference, RMS-11 does 
not indicate if the record retrieved is one of a series containing 
duplicates in that field. 
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; ^ s 



*************** 

* * 

The $NXTVOL macro is not supported by RSTS/E. * $NXTVOL * 

* * 
*************** 



8.2.8 $NXTVOL 

The $NXTVOL macro can be used only when the Record Access Stream is 
accessing a multivolume file on magnetic tape. You execute this macro 
when you want to continue processing the current file on the next vo- 
lume before the end of the current volume is reached. See also the 
magnetic tape handling appendix of the RMS-11 User's Guide. 

Next-volume processing depends on whether your program is reading or 
writing data on the tape: 

Input File Processing 

1. RMS-11 skips all records in I/O buffers for the current 
file section. 

2. RMS-11 requests the next tape volume from the file pro- 
cessor : 

• If there is no next volume, RMS-11 returns error code 
ER$EOF. 

• If there is another volume, the file processor 
rewinds' the current volume, requests the system oper- 
ator to mount the next volume, and reads the header 
label (HDR1) of the first file section on the next 
tape. If the tape is not the proper volume, the pro- 
cessor requests the operator to mount the correct 
tape and repeats this step. 

3. The operation terminates. 

Output File Processing 

1. RMS-11 writes I/O buffers to the current file section in 
an implicit flush operation. 

2. RMS-11 requests the next tape volume from the file pro- 
cessor : 

a. The processor closes the current file section, writ- 
ing E0V1 and E0V2 labels and rewinding the volume. 

b. The processor requests the system operator to mount 
the next volume. 

c. The processor creates a file with the same name and 
the next higher section number and opens the file 
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for write operations. The file set identifier is 
identical with the volume identifier of the first 
volume in the volume set. 

3. The operation terminates. 



8.2.8.1 Input RAB Fields - 

BID 
BLN 
ISI 



8.2.8.2 Output RAB Fields - 

STS 
STV 



8.2.8.3 General Form - 

$NXTVOL rab[ , error [, success] ] 

where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 

error is the address of a completion routine to be called if the 
$NXTVOL operation fails. 

success is the address of a completion routine to be called if the 
$NXTVOL operation succeeds. 



^ 
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*************** 

* * 

* $PUT * 

* * 
*************** 



8.2.9 $PUT 

The $PUT macro writes a new record into an RMS-11 file. The RAB RBF 
and RSZ fields describe the record to be written. You cannot use Ac- 
cess by RFA. Put operations in Random Access Mode do not change the 
Next Record pointer. 



8.2.9.1 Input RAB Fields - 



BID 
BLN 
ISI 
KBF 
KSZ 
RAC 
RBF 
RHB 
ROP 
RSZ 
UBF 
USZ 



(Random Access Mode on Relative files only) 
(Random Access Mode on Relative files only) 



(VFC records only) 



(Locate Mode for Sequential files only) 
(Locate Mode for Sequential files only) 



8.2.9.2 Output RAB Fields - 

BKT (Sequential Access Mode on Relative files only) 

RBF (Locate Mode for Sequential files) 

RFA 

STS 

STV 



8.2.9.3 General Form - 

$PUT rab[ , error [, success] ] 

where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 

error is the address of a completion routine to be called if the 
$PUT operation fails. 

success is the address of a completion routine to be called if the 
$PUT operation succeeds. 



Record Operation Macros: $PUT 8-27 



8.2.9.4 Comments - 

• Since RMS-11 supports put operations in Sequential Access Mode only 
for Sequential files, you must set the value RB$SEQ in the RAB RAC 
field before initiating a $PUT operation on a Sequential file. 

• RMS-11 supports put operations only at the end of Sequential files. 
Your program can reach end-of-file by one of the following methods: 

— Set RB$EOF in the RAB ROP field before initiating the connect 
operation. RMS-11 sets the Current Record pointer to 
end-of-file . 

— Execute $FIND (or $GET) macros until RMS-11 returns error code 
ER$EOF. 

• RMS-11 restricts put operations on Relative files as follows: 

— No record can be written that is longer than the Maximum Record 
Size specified when the file was created. 

— The cell specified by the contents of the RAB KBF field cannot 
contain a valid record — unless you set the value RB$UIF in the 
RAB ROP field. 

— The relative record number in the RAB KBF field cannot be gre- 
ater than the Maximum Record Number specified when the file was 
created . 

• RMS-11 restricts put operations on Indexed files as follows: 

— No record can be written that is longer than the Maximum Record 
Size specified when the file was created. 

— No record can be written that is too short to contain the com- 
plete Primary Key field. The record does not have to contain 
all defined Alternate Key fields. 

• If a put operation on an Indexed file specifies a record that con- 
tains a key value already existing in the file, RMS-11 response de- 
pends on whether you allowed duplicate key values when you created 
the file: 

— If duplicates are not allowed, RMS-11 returns error code ER$DUP. 

— If duplicates are allowed, RMS-11 inserts the record after all 
records with the same key value and before a record with a 
higher key value. Then RMS-11 returns success code SU$DUP. 
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*************** 

* * 

* $REWIND * 

* * 
*************** 



8.2.10' $REWIND 

The $REWIND macro sets the context of a Record Access Stream to the 
logical beginning of the associated file. Following the operation, 
there is no Current Record, and the Next Record is the first record in 
the file; for Indexed files, the value of the RAB KRF sets the index 
that defines the first record logically. 



8.2.10.1 Input RAB Fields - 

BID 
BLN 
ISI 
KRF (Indexed files only) 



8.2.10.2 Output RAB Fields - 

STS 
STV 



8.2.10.3 General Form - 

$REWIND rab[ , error [, success] ] 

where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 

error is the address of a completion routine to be called if the 
$REWIND operation fails. 

success is the address of a completion routine to be called if the 
$REWIND operation succeeds. 



8.2.10.4 Comments - RSTS/E does not support the $REWIND macro for 
magnetic tape files only. 
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*************** 

* * 

* $TRUNCATE * 

* * 
*************** 



8.2.11 $TRUNCATE 

The $TRUNCATE macro truncates a Sequential file. If you initiate a 
truncate operation on a Relative or Indexed file, RMS-11 returns error 
code ER$IOP. 

A truncate operation deletes the Current Record and all records fol- 
lowing that record and sets Next Record to point to the end-of-file. 
Therefore, your program must successfully execute a $FIND or $GET 
macro before initiating a $UPDATE macro; otherwise, RMS-11 returns 
error code ER$CUR. 



8.2.11.1 Input RAB Fields - 

BID 

BLN 
ISI 



8.2.11.2 Output RAB Fields 

STS 
STV 



8.2.11.3 General Form - 

$TRUNCATE rab [, error [, success] ] 

where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 

error is the address of a completion routine to be called if the 

$TRUNCATE operation fails. 

success is the address of a completion routine to be called if the 

$TRUNCATE operation succeeds. 



8.2.11.4 Comments - Your program can follow a truncate operation im- 
mediately with one or more sequential put operations. 
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*************** 

* * 

* $UPDATE * 

* * 
*************** 



8.2.12 $UPDATE 

The $UPDATE macro replaces an existing record with the record des- 
cribed by the RAB RBF and RSZ fields. 

The $UPDATE operation always applies to the Current Record. 
Therefore, your program must successfully execute a $FIND or $GET 
macro before initiating a $UPDATE macro; otherwise, RMS-11 returns 
error code ER$CUR. 

RMS-11 error codes indicating an illegal input value in a RAB field do 
not affect the record being updated. 

Example ER$RSZ 

However, other errors can mean that the target record is lost. 

Example ER$WER 



8.2.12.1 Input RAB Fields - 

BID 

BLN 

ISI 

RBF 

RHB (VFC records only) 

RSZ 



8.2.12.2 Output RAB Fields - 

RFA 
STS 
STV 



8.2.12.3 General Form - 

$UPDATE rab[ , error [, success] ] 

where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 

error is the address of a completion routine to be called if the 
$UPDATE operation fails. 
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success is the address of a completion routine to be called if the 
$UPDATE operation succeeds. 



8.2.12.4 Comments - 

• RMS-11 restricts update operations on Sequential files as follows: 

— No updates on magnetic tape files or unit record devices. 

— No updates on disk Sequential files with stream format records. 

— No updates that change the length of the target record: your 
program must not change the RAB RSZ field between the get or 
find operation and the update operation. 

• For Relative files, the replacement record cannot be longer than 
the Maximum Record Size specified when the file was created. 

• For an update operation on an Indexed file that allows duplicate 
Primary Keys, the replacement record length must equal the target 
record length; that is, your program must not change the RAB RSZ 
field between the get or find operation and the update operation. 

• For an update operation on an Indexed file that does not allow du- 
plicate Primary Keys, the record length can change, but the re- 
placement record cannot be longer than the file's Maximum Record 
Size or too short to contain the complete Primary Key field. 
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*************** 

* * 

* $WAIT * 

* * 
*************** 



8.2.13 $WAIT 

The $WAIT macro suspends your program's operation until an outstanding 
asynchronous record operation completes. 



8.2.13.1 Input RAB Fields - 

BID 
BLN 
ISI 



8.2.13.2 Output RAB Fields - 

STS 
STV 

plus fields of asynchronous record operation your program is wait- 
ing for 



8.2.13.3 General Form - 

$WAIT rab[ f error[ , success] ] 

where rab is the address of an asynchronous Record Access Block repre- 
senting a Record Access Stream with an asynchronous record 
operation in progress. 

error is the address of a completion routine to be called if the 
$WAIT operation fails. 

success is the address of a completion routine to be called if the 
$WAIT operation succeeds. 
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CHAPTER 9 
PERFORMING BLOCK I/O 



Block I/O allows you to bypass the record processing capabilities of 
RMS-11. Through macros described in this chapter, you can read and 
write the virtual blocks of a file. 

CAUTION 

Many elements of the internal structure of RMS-11 files are 
not visible during record processing. With Block I/O, 
however, you can examine these elements. 

Exercise extreme caution when altering the virtual blocks of 
RMS-11-structured Sequential, Relative, or Indexed files. 

To use Block I/O, your program must do the following: 

1. Allocate one BDB for each stream* connected for Block I/O. You 
specify BDBs with the P$BDB macro between the POOL$B and POOL$E 
macros (see Chapter 2). 

2. Allocate an I/O buffer with at least 512 bytes (to support file 
operations) . Use one of the techniques described in Chapters 1 
and 2. If your program reads or writes more than one block at a 
time, allocate a buffer large enough to support all operations. 

3. Set one or both of the following values in the FAB FAC field be- 
fore initiating any file operation macros: 

FB$REA if you want to read blocks from an RMS-11 file 

FB$WRI if you want to write blocks to an RMS-11 file 

4. Initiate one of the following file operaton macros: 

$CREATE 

You create a file that can be processed only with Block 
I/O operations. RMS-11 restricts such files as follows: 



disk or magnetic tape medium 



*RMS-11 permits a single Block I/O stream for Sequential files and 
multiple streams for Relative and Indexed files. 



• Sequential organization (FB$SEQ in the FAB ORG field) 

• Undefined record format (FB$UDF in the FAB RFM field) 



6. 



$OPEN 

You access a file with any RMS-11 file organization; 
however, you can use only Block I/O operations to access 
data in the file. 

Set up a Record Access Block (see Chapter 4) and initiate a 
$CONNECT macro for each Record Access Stream. No stream can be 
connected to the file for record processing. 

Use the macros described in this chapter to processing data in the 
file. 



7. Disconnect each stream. 

8. Close the file. 

Table 9-1 summarizes the RMS-11 Block I/O macros. 
Table 9-1: RMS-11 Block I/O Macros 



Macro Name 


Description 


$READ 


Retrieve a specified number of bytes from a virtual block. 


$WRITE 


Write a specified number of bytes to a virtual block. 


$SPACE 


Move a magnetic tape a specified number of blocks. 
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*************** 

* * 

* $READ * 

* * 
*************** 



9.1 $READ 

The $READ macro retrieves a specified number of bytes from a file be- 
ginning on a specified virtual block boundary. You must supply a 
word-aligned buffer for the data. 



9.1.1 Input RAB Fields 



BKT (VBN where read starts) 

ISI 

UBF (address for input buffer) 

USZ (size of input buffer as a multiple of two bytes) 



9.1.2 Output RAB Fields 



RBF (location of data read from file) 

RSZ (number of bytes read) 

STS 

STV 



9.1.3 General Form 

$READ rab[ , error [ , success] ] 

where rab is the address of a Record Access Block containing the spec- 
ification for the read operation. 

error is the address of a completion routine to be called if the 
$READ operation fails. 

success is the address of a completion routine to be called if the 
$READ operation succeeds. 



9.1.4 Comments 

• You can read multiple blocks by specifying an appropriate multiple 
of 512 bytes in the RAB USZ field. 
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• The value RMS-11 returns in the RAB RSZ field does not count the 
terminator character received from a unit record or terminal dev- 
ice. The RAB STV field reports on that character; see the $GET 
record operation in Chapter 8. 

• If the RAB STS field contains ER$EOF, the RAB RSZ still contains 
the number of bytes transferred. 
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*************** 

* * 

* $WRITE * 

* * 

*************** 



9.2 $WRITE 

The $WRITE macro writes a specified number of bytes into a file begin- 
ning on a specified virtual block boundary. 



9.2.1 Input RAB Fields 

BKT (VBN where write starts) 

ISI 

RBF (address of first byte of one or more blocks to be written) 

RSZ (size of data to be written as a multiple of two bytes) 



9.2.2 Output RAB Fields 



STS 

STV (actual number of bytes transferred) 



9.2.3 General Form 

$WRITE rab[ ,error[ , success] ] 

where rab is the address of a Record Access Block containing the spec- 
ification for the write operation. 

error is the address of a completion routine to be called if the 
$WRITE operation fails. 

success is the address of a completion routine to be called if the 
$WRITE operation succeeds. 



9.2.4 Comments 

• You can write multiple blocks by specifying an appropriate multiple 
of 512 bytes in the RAB RSZ field. 

• If the RAB RSZ does not contain an even multiple of 512 bytes, the 
number of bytes specified are written, but the disk contents of the 
unwritten portion of the last block affected are undefined. 
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*************** 

* * 

The $SPACE macro is not supported on RSTS/E * $SPACE * 

* * 

*************** 



9.3 $SPACE 

The $SPACE macro causes a magnetic tape file to move forward or back- 
ward. The file must have been opened for Block I/O and reside of mag- 
netic tape; otherwise, RMS-11 returns error code ER$IOP. 



9.3.1 Input RAB Fields 



BKT (number of blocks to be spaced; sign indicates direction) 

ISI 

ROP (can contain RB$ASY; see Chapter 4) 



9.3.2 Output RAB Fields 



STS 

STV (number of blocks spaced) 



9.3.3 General Form 

$SPACE rab[ , error [, success] ] 

where rab is the address of a Record Access Block containing the spec- 
ification for the spacing operation. 

error is the address of a completion routine to be called if the 
$SPACE operation fails. 

success is the address of a completion routine to be called if the 
$SPACE operation succeeds. 



9.3.4 Comments 

RMS-11 examines only the lower addressed byte of the one-word BKT 
field. RMS-11 interprets this byte as a signed 15-bit integer: 

• A positive integer represents the number of blocks the file is to ^^ 
be spaced forward f^^ 
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A negative number represents the number of blocks the file is to be 
backspaced . 
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APPENDIX A 
RMS-11 COMPLETION CODES 



All RMS-11 file and record operations return a completion code into 
the STS field of the associated control block (FAB or RAB) . A symbol- 
ic name is defined for each code, with one of the following forms: 

Successful completion codes: 

SUScod 
Error completion codes: 

ER$cod 

where cod represents the success qualifier or the reason the operation 
failed. 

For certain error conditions, RMS-11 uses the STV field to communicate 
additional information to your program. The tables in this appendix 
list all instances where an STS code indicates the presence of further 
information in the STV field. 

A limited number of severe error conditions cause RMS-11 to use a 
fatal error crash routine. Section A. 3 describes these conditions and 
the crash routine. 



A.l SUCCESSFUL COMPLETION CODES 

Table A-l describes successful completion codes returned by RMS-11 op- 
erations. 



Table A-l: RMS-11 Successful Completion Codes 



Symbolic 


Numeric 


STV Field 


Description 


Value 


Value 


Value 




SU$SUC 


1/1 




Operation successful without 
qual if ication. 


SU$DUP 


2/2 




Conditional success: A record 
inserted into an Indexed file by 
a put or update operation con- 
tains at least one key value 
present in another record. 


SU$IDX 


3/3 


RMS-11 code 


A put or update operation on an 
Indexed file ended successfully, 
but RMS-11 could not optimize 
the index structure during the 
operation. Therefore, RMS-11 
will require extra I/O opera- 
tions to retrieve the record. 
With this success code, RMS-11 
can include an RMS-11 error code 
in the STV field of the control 
block to indicate why the index 
structure was not updated. 


SU$RRV 


4/4 




No longer a valid completion 
code. See ER$RVU in Table A-2. 



A-2 Successful Completion Codes 



A. 2 ERROR COMPLETION CODES 



Table A-2 shows: 

• the RMS-11 error completion codes in alphabetical order by symbolic 
value 

• the numeric values of the codes in both octal and decimal radix 

• a brief explanation of the cause of the error 

When Table A-2 indicates that the STV field contains a file processor 
code (with the term fipcode) , refer to the description of such codes 
in one of the following manuals: 

• Error code appendix of the IAS/RSX-11 I/O Operations Reference Man- 
ual 

• User recoverable error messages in an appendix of the RSTS/E Pro- 
gramming Manual. Note that the value returned in STV is the nega- 
tive of the decimal value shown in the Programming Manual. That 
is, if STV contains "-20.," look up "20." 

When Table A-2 indicates that the Status Value field contains an FSS 
directive error code (with the term fsscode) , you should refer to the 
error code appendix of the RSTS/E System Directives Manual for a des- 
cription of the codes. 



Table A-2: RMS-11 Error Completion Codes 



Symbolic 
Va 1 ue 



ER$ABO 



ER$ACC 



ER$ACT 



Numeric 
Va 1 ue 



177760/-16, 



177740/-32. 



177720/-48, 



STV Field 
Value 



ER$STK/ER$MAP 



fipcode 



File activity 



Description 



Operation aborted: Stack save 
area exhausted or memory resi- 
dent control structures corrupt- 
ed . 

File processor error: File pro- 
cessor could not access the 

file. 

precludes operation. 

Example You attempted to close 
a file before an asyn- 
chronous record opera- 
tion finished. 
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Table A-2 (continued) 



Symbol ic 
Value 



Numeric 
Value 



STV Field 
Value 



Description 



ER$AID 
ER$ALN 
ER$ALQ 



ER$ANI 

ER$AOP 
ER$AST 



ER$ATR 

ER$ATW 
ER$BKS 
ER$BKZ 
ER$BLN 
ER$BOF 



177700/-64. 
177660/-37. 
177640/-96. 



177620/-112. 

177600/-128. 
177560/-144, 



177540/-160, 

177530/-168 
177520/-176, 

177500/-192, 

177460/-208. 

177440/-224, 

177430/-232, 



XAB address 



XAB address 



XAB address 



XAB address 



f ipcode 



f ipcode 



XAB address 



The area indicated by the XAB 
does not exist in the file. 

Illegal alignment value for 
Placement Control. 

Illegal allocation quantity: 
The quantity exceeds 65K blocks 
during file creation on a 
non-Large Files RSTS/E system 
or equals zero during an expli- 
cit file extension operation. 

Records in a file on 

ANSI-labeled magnetic tape are 

variable-length, but not in 
ANSI-D format. 

Invalid type of allocation. 

Invalid operation at AST level: 
You attempted to issue a syn- 
chronous operation from an asyn- 
chronous record operation com- 
pletion routine. 

File processor error: Read fai- 
lure on file attributes. 

Invalid File ID. See ER$FID. 

File processor error: Write fa- 
ilure on file attributes. 

File bucket size exceeds maximum 
for operating system. 

Area bucket size exceeds maximum 
for operating system. 

Control block (FAB, RAB, or XAB) 
length is invalid. 

Beginning of file detected dur- 
ing magnetic tape spacing opera- 
tion. 
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Table A-2 (continued) 



Symbolic 
Va 1 tie 



ER$BPA 



ER$BPS 



ER$BUG 



ER$CCR 



ER$CHG 



ER$CHK 



ER$CLS 
ER$COD 
ER$CRE 



Numeric 
Value 



177420/-240. 



177400/-256. 



177360/-272. 



177340/-288. 



177320/-304. 



177300/-320. 



177260/-336 



177240/-352. 



177220/-368. 



STV Field 
Value 



f ipcode 



XAB address 



f ipcode 



Description 



Invalid I/O buffer: Private 

buffer pool not on word bounda- 
ry. 

Invalid I/O buffer: Private 

buffer pool size not a multiple 
of two bytes. 

RMS-11 aborts your task because 
it detected an internal error. 
Contact a DIGITAL Software Spe- 
cialist. 

You attempted to connect more 
than one record access stream to 
a Sequential file. 

During an update operation, you 
attempted to change a key field 
that does not allow changes. 



Indexed file bucket 
Do as many of the 
steps as necessary: 

1. Move the disk pack 
the file to ano 
and try the proc 
If it works, th 
caused by a hardwa 
ilure. 

2. Recreate the file 
RMS IF L or RMSCNV u 
this works, the 
bucket was in an i 
not used during 
access by Primary 

3. Restore the file 
last backup copy. 



corrupted . 
following 

containing 
ther device 
ess again, 
e error was 
re read fa- 
using the 
tility. If 
corrupted 
ndex bucket 
sequential 
Key. 
from your 



File processor error: During 
RMS-11 file close operation. 



XAB type is invalid for the 
ganization or operation. 



or- 



File processor error: File pro- 
cessor could not create file. 
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Table A-2 (continued) 



Symbol ic 
Value 



Numeric 
Value 



STV Field 
Value 



Description 



ER$CUR 



ER$DAC 



ER$DAN 



ER$DEL 



ER$DEV 



ER$DFW 



ER$DIR 
ER$DME 

ER$DNF 
ER$DNR 
ER$DPE 
ER$DTP 



177200/-384, 



177160/-370, 



177140/-416. 



177120/-432. 



177100/-448, 



177070/-456. 



177060/-464. 
177040/-480, 

177020/-496, 
177000/-512. 
176770/-520. 
176760/-528. 



f ipcode 



XAB address 



f ipcode 



f ipcode 
XAB address 



No Current Record: Delete, 

truncate, or update operation 
was not immediately preceded by 
a successful get or find. 

File processor error: File pro- 
cessor deaccess failure during 
RMS-11 file close operation. 

Invalid area number specified in 
Key XAB DAN field. 

Record accessed by RFA access 
mode has been deleted. 

• Syntax error in device name 

• No such device 

• Inappropriate device for op- 
eration 

Example You attempted to 
create an Indexed 
file on magnetic 
tape . 

File processor error: File pro- 
cessor could not write bucket; 
RMS-11 deferred the I/O opera- 
tion until it needed the I/O 
buffer for another bucket be- 
cause the user program specified 
Deferred Write. 

Syntax error in filespec direc- 
tory name. 

Dynamic memory exhausted: An 
RMS-11 buffer pool has insuffi- 
cient free space. 

Directory not found. 

Device not ready. 

Device positioning error. 

Invalid key data type. 
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A-6 Error Completion Codes 



Table A-2 (continued) 



Symbol ic 
Value 



ER$DUP 



ER$ENT 



ER$ENV 



ER$EOF 



ER$ESS 



ER$EXP 



ER$EXT 



ER$FAB 



ER$FAC 



ER$FEX 



ER$FID 



Numeric 
Value 



176740/-544. 



176720/-560. 



176700/-576. 



STV Field 
Value 



176660/-592. 



176640/-608. 



176630/-616. 



176560/-656, 



176540/-672, 



177530/-168, 



f ipcode 



176620/-624. fipcode 



176600/-640, 



Description 



Invalid record operation: You 
attempted to insert a record 
that would cause duplicate va- 
lues in a key field where dupli- 
cates are not allowed. 

File processor error: File pro- 
cessor could not enter filespec 
in directory. 

You attempted an operation when 
the RMS-11 routines were not in 
the task: In MACRO-11, the op- 
eration or file organization was 
not specified in ORG$ macro; in 
BASIC-PLUS-2, you didn't specify 
correct switches with BUILD com- 
mand . 

• For record processing: End 
of file. 

• For Block I/O: Invalid VBN. 

Expanded file-name string area 
in NAM Block is too short. 

File expiration date not re- 
ached . 

File processor error: During 
RMS-11 file extension operation. 

FAB BID field does not contain 
FB$BID. 

Invalid record operation: 
Operation does not match access 
declaration made when file was 
created or opened. 

You tried to create a file that 
exists. 

Invalid file ID. 
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Table A-2 (continued) 



Symbolic 
Value 



ER$FLG 



ER$FLK 

ER$FND 

ER$FNF 

ER$FNM 
ER$FOP 

ER$FSS 

ER$FUL 
ER$IAN 
ER$IDX 

ER$IFI 



Numeric 
Value 



176520/-688. 



176500/-704. 

176460/-720. 

176440/-736. 

176420/-752. 
176400/-768. 

176370/-776. 

176360/-784. 
176340/-370. 
176320/-816. 

176300/-832. 



STV Field 
Value 



XAB address 



f ipcode 



f sscode 



XAB address 



Description 



Invalid combination of key char- 
acteristics. 

Example No duplicate key va- 
lues, but key values 
can change during up- 
date operations. 

File locked by another user: 
You cannot access the file be- 
cause your sharing specifica- 
tions cannot be met. 

File processor error: File pro- 
cessor could not find filespec 
in specified directory. 

File not found during file open 
operation* 

Syntax error in file-name. 

Invalid file access option spec- 
ified in FAB FOP field. 

RSTS/E monitor error: the 

File-name String routine is un- 
able to parse the file-name 
string supplied by RMS-11. 

Device full: RMS-11 cannot cre- 
ate or extend file. 

Invalid area number specified in 
Key XAB IAN field. 

Specified index was not created. 
This code can only occur in the 
STV field when STS contains 
ER$RNF. 

FAB IFI field contains invalid 
value . 



(Continued on next page) 



A-8 Error Completion Codes 



Table A-2 (continued) 



Symbol ic 
Value 



Numeric 
Value 



STV Field 
Value 



Description 



ER$IMX 

ER$INI 
ER$IOP 



ER$IRC 



ER$ISI 



ER$KBF 



ER$KEY 



176260/-848. 

176240/-864. 
176220/-880. 



176200/-896. 



176160/-912. 



176140/-928. 



176120/-944. 



XAB address 



More than 254 keys and/or areas 
defined or multiple Summary, 
Protection, or Date/Time XABs 
present during operation. 

$INIT or $INITIF macro call 
never issued. 

Illegal operation. 

Example You attempted to trun- 
cate a nonsequential 
file. 

Example You attempted to de- 
lete or extend a mag- 
netic tape file. 

Example You issued a Block I/O 
operation to a stream 
not connected for 
block operations. 

Example You issued a record 
operation to a stream 
connected for Block 
I/O operations. 

Illegal record encountered in 
Sequential file: Record-length 
field is invalid. 

RAB ISI field is invalid. You 
may have altered it or failed to 
connect the stream. 

No key specified during random 
record operation: RAB KBF field 
equals 0. 

Negative Relative Record Number 
during random operation or bad 
format in packed decimal key 
value . 



(Continued on next page) 



Error Completion Codes A-9 



Table A-2 (continued) 



Symbolic 
Value 



ER$KRF 



ER$KSZ 
ER$LAN 

ER$LBL 
ER$LBY 



ER$LCH 
ER$LEX 
ER$LOC 
ER$MAP 



ER$MKD 



Numeric 
Value 



176100/-960. 



176060/-976. 
176040/-992. 

176020/-1008. 
176000/-1024. 



STV Field 
Value 



175760/-1040. 



175750/-1048. 



175740/-1056. 



175720/-1072. 



175700/-1088. 



XAB address 



XAB address 



XAB address 



f ipcode 



Description 



Invalid key of reference: 

• During random get or find op- 
eration. 

• During connect or rewind op- 
eration: Error code is re- 
turned for the first sequen- 
tial get or find operation 
following the connect or 
rewind. 

Invalid key size. 

Invalid area number specified in 
Key XAB LAN field. 

Invalid medium: Magnetic tape 
is not labeled in accordance 
with ANSI standards. 

Logical channel busy: You at- 
tempted to create or open a file 
using a logical channel in use; 
that is, you already opened a 
file on that channel. 

Invalid logical channel or unit 
number. 

You attempted to extend an area 
containing an unused extent. 

Invalid location during Place- 
ment Control. 

Memory-resident data structures, 
such as I/O buffers, corrupted. 
This code can occur in the STV 
field when Status Code contains 
ER$ABO. 

File processor error: File pro- 
cessor could not mark file for 
deletion. 



(Continued on next page) 



A-10 Error Completion Codes 



HOP 



Table A-2 (continued) 



Symbol ic 
Va 1 ue 


Numeric 
Va 1 ue 


STV Field 
Value 


Description 


ER$MRN 


175660/-1104. 




Maximum Record Number field 
contains a negative value 
during creation of Relative 
file. 

• Relative Record Number for 
random operation to Relative 
file exceeds Maximum Record 
Number specified when file 
was created. 


ER$MRS 


175640/-1120. 




Maximum Record Size is zero dur- 
ing file creation and one of the 
following is true: 

• Record format is fixed 

• File organization is Rela- 
tive. 


ER$NAM 


175620/-1136. 




Odd address in FAB NAM field on 
file open, creation, or erase 
operation. 


ER$NEF 


175600/-1152. 




You attempted a put operation to 
a Sequential file when stream is 
not positioned to end-of-file. 


ER$NID 


175560/-1168. 




Dynamic memory exhausted: Not 
enough buffer area to open an 
Indexed file. 


ER$NPK 


175540/-1184. 




You attempted to create an In- 
dexed file without defining a 
Primary Key. 


ER$OPN 


175520/-1200. 


f ipcode 


File processor error: During 
RMS-11 file open operation. 


ER$ORD 


175500/-1216. 


XAB address 


XABs not ordered properly. 


ER$ORG 


175460/-1232. 




Invalid file organization. 



(Continued on next page) 



Error Completion Codes A-ll 



Table A-2 (continued) 



Symbol ic 
Value 



Numeric 
Value 



STV Field 
Val ue 



Description 



ER$PLG 



ER$POS 



ER$PRM 



ER$PRV 



ER$RAB 



ER$RAC 



ER$RAT 



ER$RBF 



ER$RER 



175440/-1248. 



175420/-1264. 



175400/-1280. 



175360/-1296. 



175340/-1312, 



175320/-1328, 



175300/-1344, 



175260/-1360. 



175240/-1376. 



XAB address 



XAB address 



f ipcode 



A Prologue block may be corrupt- 
ed. Do as many of the following 
steps as necessary: 

1. Move the disk pack containing 
the file to another device 
and try the process again. 
If it works, the error was 
caused by a hardware read fa- 
ilure. 

2. Recreate the file using the 
RMSIFL or RMSCNV utility. 

3. Restore the file from your 
last backup copy. 

You specified a key position 
beyond the end of the record. 

File directory entry contains 
date and time information not 
semantically correct. The file 
may be corrupted. Recreate 
field using . RMSIFL or RMSCNV 
util ity. 

Privilege violation: access to 
the file denied by the operating 
system. 

RAB BID field does not contain 
RB$BID. 

Invalid or illogical record ac- 
cess option specified in RAB RAC 
field . 

You specified both Carriage Re- 
turn control and FORTRAN forms 
control . 

RAB RBF field contains an odd 
address (Block I/O access only) . 

File processor error: 

• In record processing: Read 
failure on file block. 

• In Block I/O, VBN = 0, 
illegal value. 



an 
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A-12 Error Completion Codes 



Table A-2 (continued) 



Symbolic 
Value 



Numeric 
Va 1 ue 



STV Field 
Value 



Description 



ER$REX 



ER$RFA 
ER$RFM 
ER$RLK 

ER$RMV 

ER$RNF 



ER$RNL 



ER$ROP 



ER$RPL 



ER$RRV 



ER$RSA 



ER$RSZ 



175220/-1392. 



175200/-1408. 
175160/-1424. 
175140/-1440. 

175120/-1456. 

175100/-1472. 



175060/-1488, 



175040/-1504, 



175020/-1520. 



175000/-1536. 



174760/-1552. 



174740/-1568. 



f ipcode 



ER$IDX 



f ipcode 



Record exists: During a put op- 
eration in random mode to a Re- 
lative file, you tried to insert 
a record into a cell containing 
a record. 

Invalid RFA during RFA access. 

Invalid record format. 

Target bucket locked by another 
task or another stream in the 
same program. 

File processor error: File pro- 
cessor could not remove filespec 
from directory. 

Record specified during random 
get or find operation does not 
exist in Relative or Indexed 
file. For Indexed files only, 
STV may contain ER$IDX. 

You initiated a free operation, 
but no bucket was locked. 

Invalid record processing option 
or illogical combination of va- 
lues specified in RAB ROP field. 

File processor error: Read fai- 
lure on file Prologue. 

Invalid RRV record encountered 
in Indexed file. File may be 
corrupted. Recreate field using 
RMSIFL or RMSCNV utility. 

Record stream active: In asyn- 
chronous environment, you at- 
tempted a record operation on a 
stream that is performing an op- 
eration. 



• Record size is 
Block I/O. 



zero during 
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Error Completion Codes A-13 



Table A-2 (continued) 



Symbol ic 


Numeric 


STV Field 


Description 


Value 


Value 


Value 










• Record size exceeds one of 








the following: 








— MRS for variable-length or 








VFC records. 








— magnetic tape block size. 








— data bucket size of In- 








dexed file. 








— 510(10) bytes and block 








spanning not allowed. 








— end of I/O buffer during 








Locate Mode put operation 








on Sequential file. 








• Record is too short to con- 








tain Primary Key of Indexed 








file. 








• Record size is not equal to 








size of Current Record for 








update operation on a disk 








Sequential file or on an In- 








dexed file where Primary Key 








duplicate are allowed. 








• Record size does not equal 








MRS for fixed-length records. 


ER$RTB 


174720/-1584. 


Bytes moved 


Record too big for user buffer: 
RMS-11 could not move entire re- 
cord retrieved by get operation 
to user buffer. This error does 
not destroy the context of the 
stream. Rather, the stream's 
context is updated as if the op- 
eration were completely success- 
ful and as much of the record as 
possible is moved to the user 
buffer. 


ER$RVU 


174710/-1592. 




During a put or update opera- 
tion, RMS-11 moved the specified 
record to the file successfully, 
but could not update one or more 
Record Reference Vector (RRV) . 
The file is corrupted, but you 
can retrieve every record via 
the Primary index. Therefore, 
you should create a new Indexed 
file and populate it from the 
bad file using either the RMSIFL 
or the RMSCNV utility. 



(Continued on next page) 



A-14 Error Completion Codes 



Table A-2 (continued) 



Symbol ic 
Va 1 ue 



Numeric 
Value 



STV Field 
Value 



Description 



ERSSEQ 



ER$SHR 
ER$SIZ 

ER$STK 



ER$SYS 



ER$TRE 



ER$TYP 



ER$UBF 



L 



ER$USZ 
ER$VER 

ER$VOL 



174700/-1600. 



174660/-1616. 



174640/-1632. 



174620/-1648. 



174600/-1664. 



174560/-1680. 



174540/-1696. 



174520/-1712. 



174500/-1728. 
174460/-1744 

174440/-1760. 



XAB address 



Directive or 
QIO status 
error code 



XAB address 



Invalid record operation: 

During a sequential put opera- 
tion to an Indexed file, Primary 
Key of record to be written is 
not equal to or greater than key 
of previous record. 

You specified allow write de- 
claration for Sequential file. 

Invalid key size. 

Example Key is bigger than 
Maximum Record Size. 

During asynchronous record oper- 
ation, RMS-11 found the stack 
too big to saved. This code can 
only occur in the STV field when 
Status Code contains ER$ABO. 

The interface between RMS-11 and 
the operating system has 

changed. Report this error on 
an SPR to DIGITAL. 

Index in Indexed file is cor- 
rupted. Recreate file using 
RMSIFL or RMSCNV utility. 

Syntax error in extension, such 
as more than three characters 
specified . 

User buffer improperly 

specified: address is either 
zero or buffer is not 

word-aligned (for Block I/O ac- 
cess only) . 

User buffer length equals zero. 

Syntax error in file version 
number . 

Nonzero relative volume number. 



(Continued on next page) 



Error Completion Codes A-15 



Table A-2 (continued) 



Symbolic 
Value 



Numeric 
Value 



STV Field 
Va 1 ue 



Description 



ER$WCD 

ER$WER 
ER$WLK 
ER$WPL 
ER$XAB 
ER$XTR 



174430/-1768. 



174420/-1776. 



174410/-1784. 



174400/-1792. 



174360/-1808. 



174340/-1824. 



f ipcode 



f ipcode 



XAB address 



Explicit or default file specif- 
ication field contains wild card 
character . 

File processor error: Write fa- 
ilure on file block. 

File processor error: Device is 
write locked. 

File processor error: Error 
while writing Prologue. 

FAB XAB field or XAB NXT field 
contains an odd address. 

Explicit or default file specif- 
ication contains extraneous 
field. 



A-16 Error Completion Codes 



A. 3 FATAL ERROR CRASH ROUTINE 

RMS-11 issues a BPT instruction whenever it encounters an inconsistent 
internal conditions. This action is taken only when RMS-11 cannot 
continue processing because it might damage your files or task image. 

Example When RMS-11 encounters an invalid FAB or RAB, it cannot per- 
form a normal error routine because it has no recognizable 
control block to set a status code in. 

The BPT instruction generated is in the RORMSA module of RMS-11. The 
general registers contain the following values at the time this in- 
struction is executed: 

RO = RMS-11 error code 
Rl = Entry Stack Pointer value 
R2 = Entry return Program Counter 
R3 = Address of system impure area 

General registers Rl and R2 are always valid if the crash routine is 
caused by a fatal user call error (described in Section A. 3.1). When 
the crash routine is used because of inconsistent . internal conditions 
(described in Section A. 3. 2), the contents of Rl and R2 can be mean- 
ingless if RMS-11 was executing an asynchronous record operation. 



A. 3.1 Fatal User Call Errors 

If general register RO contains 176600(8) (ER$FAB) or 175340(8) 
(ER$RAB) , your program initiated an RMS-11 operation using an invalid 
control block: FAB for file operations and RAB for record operations. 
This condition can occur for any one of the following reasons: 

• The address of the control block is 0. 

• The address of the control block is odd. 

• The control block's BID field does not contain the proper block 
identifier code: FB$BID for FABs and RB$BID for RABs . 

Example On RSX-11M, a fatal user call error resulted in: 

TASK "TTnn " TERMINATED 

T BIT TRAP OR BPT EXECUTION 

PC =021144 

PS=170004 

R0=175340 

Rl=001162 

R2=003646 

R3=045276 

R4=000000 

R5=001164 

SP=001126 



RMS-11 Fatal Error Crash Routine A-17 



A. 3. 2 RMS-11 Inconsistent Internal Conditions Errors 

If general register RO contains 177360(8) (ER$BUG) or 175720(8) 
(ER$MAP) , RMS-11 encountered a fatal internal problem. Such condi- 
tions can be caused by your program (destroying some internal RMS-11 
data base, for example), but RMS-11 can also be responsible. 

If one of your tasks crashes with one of these error codes, send a 
Software Performance Report (SPR) to DIGITAL with the following infor- 
mation: 

• The contents of the general registers 

• The first ten words, at a minimum, or all words on the system stack 

• The operation your task was performing (open, get, put, and so on) 

• The organization of the file being processed 

• A load map of the task (produced by the Task Builder utility) 
• A post-mortem dump 



A-18 RMS-11 Fatal Error Crash Routine 



APPENDIX B 
SAMPLE CODE SEGMENTS 



The programs and code segments included in this appendix work; that 
is, they run, performing the indicate RMS-11 operations, without 
error. They are samples of programs that do run, but you should not 
construe them to be examples of approved programming techniques. 



B.l COPYING SEQUENTIAL FILES 

The sample code segments in this section demonstrate the copying of 
records from an existing Sequential file to a new Sequential file. 



DEMO . RMS 

PROGRAM TO COPY RECORDS FROM A SEQUENTIAL FILE NAMED 
FILE1.DAT TO A NEW SEQUENTIAL FILE NAMED FILE2.DAT 



STEP 1 



;STEP 2: 



FAB1: 



NAME1: 



ACCESS THE NECESSARY RMS MACROS 
MCALL $INIT , ORG$ , FAB$B , RAB$B , POOL$B , $CREATE , $OPEN , $CLOSE 
MCALL $CONNECT , $GET , $PUT , $FETCH , $STORE , $COMPARE 

DEFINE CONTROL BLOCKS AND FILE NAME STRINGS 

THE FAB FOR THE INPUT FILE, WHICH ALREADY EXISTS, WILL BE 
FILLED WITH MOST OF THE ESSENTIAL INFORMATION CONCERNING 
FILE1.DAT WHEN THE FILE IS OPENED. THE PROGRAM NEED ONLY 
SPECIFY ENOUGH INFORMATION TO OPEN THE FILE. 



FAB$B 



;FAB FOR FILE1.DAT 





F$FNA 


NAME1 




F$FNS 


9 




F$LCH 


1 




FAB$E 




.ASCII 


/FILE1. 


DAT/ 


;HERE, 


AND WITH 


FILE2, 



; ADDRESS OF NAME STRING 
; STRING IS 9 CHARACTERS LONG 
; ACCESS ON CHANNEL 1 
;END OF FAB1 
;NAME STRING FOR FAB1 
WE ASSUME THAT THE FILE EXISTS 

;ON THE SYSTEM DISK UNDER THE ACCOUNT ON WHICH WE ARE 

; LOGGED IN. 

.EVEN ; (CONTROL BLOCKS MUST BE WORD ALIGNED) 

;THE FAB FOR THE OUTPUT FILE, WHICH DOES NOT YET EXIST, MUST 
;BE FILLED WITH THE INFORMATION NECESSARY TO CREATE IT (AS IN 
;THE PREVIOUS CASE, SOME FIELDS SIMPLY CONTAIN DEFAULT VALUES 
;AND ARE NOT EXPRESSED EXPLICITLY) . SOME OF THIS INFORMATION 



FAB 2: 



NAME2: 
RAB1: 



RAB2: 



;WILL 

;FILLE 

FAB$B 

F$FNA 

F$FNS 

F$LCH 

F$FAC 

FAB$E 

.ASCII 

.EVEN 

RAB$B 

R$FAB 

R$RAC 

R$UBF 

R$USZ 

R$RHB 

RAB$E 
RAB$B 
R$FAB 
R$RAC 
R$RBF 
R$RSZ 
R$RHB 

RAB$E 



DEPEND ON THE CHARACTERISTICS OF FILE1.DAT, AND MUST BE 
D IN AT RUN-TIME AFTER FILE1.DAT HAS BEEN OPENED. 
;FAB FOR FILE2.DAT 
NAME2 ; ADDRESS OF NAME STRING 
9 ; STRING IS 9 CHARACTERS LONG 
2 ;ACCESS ON CHANNEL 2 
FB$PUT ;WRITE ACCESS REQUIRED 

;END OF FAB 2 
/FILE2.DAT/ ;NAME STRING FOR FAB2 



FAB1 

RB$SEQ 

RECBUF 

500 

HEDBUF 



FAB 2 

RB$SEQ 

RECBUF 

500 

HEDBUF 



RAB FOR FI 
ADDRESS OF 
SPECIFY SE 
ADDRESS OF 
SIZE OF TH 
ADDRESS OF 

(NECESSARY 
END OF RAB 
RAB FOR FI 
ADDRESS OF 
SPECIFY SE 
ADDRESS OF 
SIZE OF TH 
ADDRESS OF 

(NECESSARY 
END OF RAB 



LE 1 . DAT 

OWNER (FAB) 
QUENTIAL ACCESS 

RECORD BUFFER FOR $GETS 
IS BUFFER (500. BYTES) 

RECORD HEADER BUFFER 

FOR VFC RECORDS ONLY) 
1 
LE2.DAT 

OWNER 
QUENTIAL ACCESS 

RECORD BUFFER FOR $PUTS 
IS BUFFER (500. BYTES) 

RECORD HEADER BUFFER 

FOR VFC RECORDS ONLY) 
2 



;STEP 3: 
RECBUF: .BLKW 
HEDBUF: .BLKW 



ALLOCATE 

250. 

128. 



THE BUFFERS SPECIFIED ABOVE 



;STEP 4: 



POOL$B 

P$FAB 

P$RAB 

P$BDB 

P$BUF 

POOL$E 



GENERATE RMS INTERNAL SPACE POOL 

;BEGIN POOL SPECIFICATION 
2 ;A FAB FOR EACH FILE 
2 ;A RAB FOR EACH FAB 
2 ;AN I/O BUFFER FOR EACH RAB 
1024 ;MINIMUM BUFFER SIZE IS 512. 
;END OF POOL SPECIFICATION 



BYTES 



;STEP 5: DEFINE THE RMS FUNCTIONALITY REQUIRED 

ORG$ SEQ,<CRE,GET,PUT> ;SEQUENTIAL FILES ONLY, $FIND, 

;$UPDATE, $DELETE NOT REQUIRED 



;STEP 6: 



ERROR: 



;STEP 7: 



PROVIDE A GENERAL ERROR ROUTINE TO HANDLE UNEXPECTED 
ERRORS WHICH MIGHT OCCUR (WHAT IF FILE1.DAT DID NOT 
EXIST, OR CONTAINED A RECORD LARGER THAN 500 BYTES?). 
THIS IS AN ALTERNATIVE TO THE 'COMPLETION ROUTINE 1 
FUNCTION PROVIDED BY RMS. 

(CODE WHICH WILL HANDLE THE ERROR, PROMPT AT THE TERMINAL FOR 

FURTHER INSTRUCTIONS, ETC.) 



WRITE THE PROGRAM 



START: 



$INIT 
$OPEN 
MOV 



#FAB1 
#FAB1,R0 



INITIALIZE RMS. 
OPEN FILE1.DAT, 
SET UP FOR $COMPARE: 



B-2 Sample RMS-11 Programs 



1$: 



2$: 



3$: 



4$: 



5$: 



6$: 

DONE: 



1$: 



$ COM PARE 

BGT 

JSR 

MOV 

SFETCH 

$STORE 

$FETCH 

$STORE 

$FETCH 

$STORE 

$FETCH 

$STORE 

$FETCH 

$STORE 



#0,STS,R0 
1$ 

PC , ERROR 
#FAB2,R1 
R2,RAT,R0 
R2,RAT,R1 
R2,RFM,R0 
R2,RFM,R1 
R2,FSZ,R0 
R2,FSZ,R1 
R2,MRN,R0 
R2,MRN,R1 
R2,MRS,R0 
R2,MRS,Rl 



NEG STS VALUE MEANS OPEN FAILURE 

BRANCH IF SUCCESSFUL 

OTHERWISE EXECUTE ERROR ROUTINE. 

COMPLETE INITIALIZATION OF FAB2: 

GET RAT FIELD FROM FAB1 

AND MOVE IT INTO FAB2; 

DO THE SAME WITH THE RFM FIELD; 

FSZ IS PERTINENT ONLY IF FILE1.DAT 
MAY CONTAIN VFC RECORDS. 
YOU MAY OR MAY NOT WISH TO TRANSFER 
MRN, MRS, AND FOP. IF MRN IS COPIED, 
REMEMBER THAT IT IS A 2-WORD FIELD, 
AND WILL DESTROY THE CONTENTS OF R3. 



NOW CREATE FILE2.DAT (R1=FAB2) : 

CHECK FOR FAILURE 

BRANCH IF SUCCESSFUL 

OTHERWISE EXECUTE ERROR ROUTINE. 

CONNECT THE RABS. 



BRANCH IF SUCCESSFUL 



INITIALIZATION OF FAB2 SHOULD NOW BE COMPLETE EXCEPT FOR ANY 
SPECIAL CASES (FOR EXAMPLE, IF FILE2.DAT IS ON MAGNETIC TAPE, 
YOU MAY WISH TO SET THE BLS FIELD) . 

$FETCH R2,ALQ,R0 

$STORE R2,ALQ,R1 

$CREATE Rl 

$COMPARE #0,STS,R1 

BGT 2$ 

JSR PC, ERROR 

MOV #RAB1,R0 

MOV #RAB2,R1 

$CONNECT RO 

$COMPARE #0,STS,R0 

BGT 3$ 

JSR PC, ERROR 

$CONNECT Rl 

$COMPARE #0,STS,R1 

BGT 4$ 

JSR PC, ERROR 

$GET RO 

$COMPARE #ER$EOF,STS,R0 

BEQ DONE 

SCOMPARE #0,STS,R0 

BGT 5$ 

JSR PC, ERROR 

$FETCH R2,RSZ,R0 

$STORE R2,RSZ,R1 

$PUT Rl 

$COMPARE #0,STS,R1 

BGT 6$ 

JSR PC, ERROR 

BR 4$ 

MOV #FAB1,R0 

MOV #FAB2,R1 

$CLOSE RO 

$COMPARE #0,STS,R0 

BGT 1$ 

JSR PC, ERROR 

$CLOSE Rl 

$COMPARE #0,STS,R1 

BGT 2$ 

JSR PC, ERROR 



GET A RECORD FROM FILE1.DAT. 

WERE WE AT END-OF-FILE? 

IF SO, CLEAN UP AND EXIT. 

SOME OTHER ERROR? 

BRANCH IF SUCCESSFUL 

IF SO, HANDLE IT. 

COPY RECORD LENGTH FROM 

RAB1 TO RAB2. 

OUTPUT THE RECORD TO FILE2.DAT. 

; BRANCH IF SUCCESSFUL 

;LOOP UNTIL DONE. 

;BACK TO THE FABS FOR $CLOSE. 



BRANCH IF SUCCESSFUL 



Sample RMS-11 Programs B-3 



2$: 



RMS IS NOW DONE: FILE2.DAT NOW CONTAINS ALL THE DATA RECORDS 
OF FILE1.DAT, PLUS OTHER INFORMATION (MRS, MRN, ETC.) 
YOU CHOSE TO DUPLICATE. INSERT YOUR OWN EXIT CODE AND EXIT. 
. END START 



B-4 Sample RMS-11 Programs 



B.2 COUNTING WORDS IN A SEQUENTIAL FILE 

This sample program reads through a sequential file named RNO.DOC, 
noting pages and counting words. The program uses RMS-11 for terminal 
I/O. 



TITLE WORDS. MAC 

SBTTL READ A DOCUMENTATION FILE AND COUNT THE WORDS 

ENABL REG ; SO CAN USE RO, Rl, ETC. 

NLIST ME 

NLIST BIN 

PROGRAM TO READ A DOC FILE PRODUCED BY RUNOFF OR RNO AND 

COUNT THE WORDS, 

STORING ENTRIES IN AN RMS ISAM FILE 



MCALL 

MCALL 

MCALL 

MCALL 

$GNCAL 

$FBCAL 

$RBCAL 



EXIT$S 

ORG$,POOL$B,$INIT 
$GNCAL, FAB$B , RAB$B , XAB$B 
$FBCAL,$RBCAL 



; THE FAB FOR THE INPUT DOC FILE, NAMED RNO.DOC, MUST 

; COMPLETELY DESCRIBE THE FILE AT ASSY TIME TO SAVE RUN TIME. 



.SBTTL 


RMS-11 


DATA BLOCKS 


.PAGE 






.EVEN 






DOCFAB: 


FAB$B 






F$BPA 







F$BPS 







F$DNA 







F$DNS 







F$FAC 


FB$GET 




F$FNA 


DOC NAM 




F$FNS 


DOCNML 




F$FOP 







F$LCH 


1 




F$NAM 







F$ORG 


FB$SEQ 




F$RFM 


FB$STM 




F$RTV 







F$SHR 







F$XAB 







FAB$E 




DOC NAM: 


.ASCII 


/RNO.DOC/ 


DOCNML 


= ,-DOCNAM 


; NEED 


CRT TO 


OUTPUT MESS 


!even 






CRTFAB 


FAB$B 






F$FAC 


FB$PUT 



BEGIN MINIMUM INITIALIZATION 

NO PRIVATE BUFFER POOL 

DITTO 

USE SYSTEM DEFAULTS 

DITTO 

ONLY GET RECORD OPERATIONS 

FILE NAME ADDRESS 

FILE NAME LENGTH 

NOT CONTIGUOUS 

LOGICAL CHANNEL FOR FILE 1 

NO NAM BLOCK 

FILE ORGANIZATION 

DOC FILES ARE STREAM 

VOLUME CLUSTERSIZE 

NOBODY ELSE 

NO XABs 

END INITIALIZATION BLOCK 

ASSUME SYSTEM DEFAULTS 



BEGIN MINIMUM INITIALIZATION 
OUTPUT ONLY 
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F$FNA 


CRTNAM 




F$FNS 


CRTNML 




F$LCH 


3 




F$ORG 


FB$SEQ 




F$RFM 


FB$VAR 




FAB$E 




CRTNAM : 


.ASCII 


/TI:/ 


CRTNML 


= .-CRTNAM 



FILE NAME ADDRESS 

FILE NAME LENGTH 

LOGICAL CHANNEL FOR FILE 

FILE ORGANIZATION 

CRTS ARE VARIABLE 

END INITIALIZATION BLOCK 

ASSUME SYSTEM DEFAULTS 



INPUT RECORD IS SINGLE CHARACTER STRING, VARIABLE IN LENGTH 
THOUGH MOST WILL BE 70 CHARACTERS LONG (MARGINS 70). 



BEGIN INITIALIZATION BLOCK 
ADDRESS OF ASSOCIATED FAB 
ONE AT A TIME 
MULTI-BUFFER COUNT 
RECORD ACCESS MODE(S) 
USER RECORD BUFFER ADDRESS 
USER-SET RECORD SIZE 
END INITIALIZATION BLOCK 

BEGIN INITIALIZATION BLOCK 
ADDRESS OF ASSOCIATED FAB 
RECORD ACCESS MODE 

END INITIALIZATION BLOCK 



.EVEN 






DOCRAB: 


RAB$B 






R$FAB 


DOC FAB 




R$MBC 


1 




R$MBF 


1 




R$RAC 


RB$SEQ 




R$UBF 


DOCRCD 




R$USZ 


DOCRCL 




RAB$E 




CRTRAB: 


RAB$B 






R$FAB 


CRTFAB 




R$RAC 


RB$SEQ 




R$ROP 


RB$EOF 




RAB$E 




.SBTTL 


BUFFERS 


AND MESSAGES 


• PAGE 






; BUFFERS 





DOCRCD: . REPT 80. 

.BYTE 040 

.ENDR 
DOCRCL = .-DOCRCD 
.EVEN 



WDCNT 
CHRCNT 
RECLEN 



XLTBUF: 
PAGENO: 
LINENO: 



.WORD 
.WORD 
.WORD 



.WORD 
.WORD 
.WORD 
.WORD 





1,10. ,100 







INPUT RECORD BUFFER 
FILL WITH SPACES 



; COUNT WORDS IN FILE 

; COUNT CHAR IN RCDS AS DONE 

; STORE RCD LENGTH AFTER RMS 

RETURNS IT 

; STOPPER FOR SCAN 

, ,1000. ,10000. ,0 ; POWERS OF 10 
; PAGE COUNTER 
; LINE COUNTER 



ARGUMENTS LISTS FOR RMS I/O OPERATIONS 



DOCLST: 
CRTLST: 



.WORD 
• WORD 
■ WORD 
.WORD 



VECTOR TABLES 



CHCODE; 



.WORD 
.WORD 
.WORD 



DOCRAB 

1 

CRTRAB 



014 
040 
055 



LENGTH OF ARGUMENT LIST 
RAB FOR RECORD BEING MOVED 
LENGTH OF ARGUMENT LIST 
RAB FOR RECORD BEING MOVED 



FORM FEED 

SPACE 

HYPHEN 
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imppMiM 



CHCEND = .-CHCODE 
CHPRCS 



.WORD 
.WORD 
.WORD 
.WORD 



FFEED 
SPACE 
HYFEN 
NOTSPA 



NLIST BIN 



MESSAGES 



ERRMSG: 

ERRNBR: 

ERRMSL 

BGNMSG: 

BGNMSL 

ENDMSG: 

ENDMSL 

OPNMSG: 

OPNMSL 

FFMSG: 

FFMSL = 

WDMSG: 

WDMSL = 

LINMSG: 

LINMSL 
BLKS3: 



FILID 
DOC ID 
STVID 
.SBTTL 
. PAGE 
.LIST 



.ASCII / ERROR / 

.ASCII /000000/ 
■ .-ERRMSG 

.ASCIZ /START WORDS PROGRAM / 
= .-BGNMSG 

.ASCIZ /END WORDS PROGRAM / 
= .-ENDMSG 

.ASCII /RNO.DOC OPENED/ 
= .-OPNMSG 

.ASCII /PAGE / 

.-FFMSG 

/ WORDS IN THIS LINE. 



FILL IN ERROR CODES 



•ASCIZ 
; .-WDMSG 

.ASCII /LINE IS TOO LONG./ 

.ASCIZ / CONTINUING WITH NEXT LINE./ 
= .-LINMSG 

.ASCIZ / / 



TOTAL WORDS = 



/ 



.ASCIZ 
.ASCIZ 
.ASCIZ 
MACROS 



BIN 



/FILE/ 
/DOC / 
/STV / 



MACROS 



.MACRO 



C: 



ENDM 



MACRO 



MOVWD 
MOV 

MOV 

CLR 

MOVB 

INC 

CMPB 

BNE 



XLT28 

MOV 

MOV 

MOV 

MOV 

ADD 

JSR 

MOV 



A f B,?C 
A,R2 



; MOVE STRING A TO THE AREA 
; DESIGNATED BY B, COUNTING THE 



B,R3 
Rl 

(R2)+, (R3)+ 
Rl 

0, (R2) 
C 



A,B 
R0,-(SP) 

5,R0 
A,R1 

B,R2 

6,R2 
PC,XLT8 
(SP) + ,R0 



CHARACTERS AS YOU GO 

INITIALIZE COUNTER 

MOVE ONE CHARACTER 

COUNT IT 

CHECK NEXT SOURCE WORD CHAR 

GO BACK FOR MORE IF NOT ZERO 



16-BIT NBR TO OCTAL ASCII 

STORE RO AWAY 

5 IS NBR OF CHARS IN BFR 

PUT IN NBR 

MOVE IN RCV BFR 

MOVE TO END OF RCV BFR 

DO IT 

BRING RO BACK FROM THE STACK 
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.ENDM 



.MACRO 


XLT210 


A,B 




MOV 


RO f -(SP) 




MOV 


R1,-(SP) 




MOV 


R2,-(SP) 




MOV 


R3,-(SP) 




MOV 


R4,-(SP) 




MOV 


R5,-(SP) 




MOV 


A,R0 




MOV 


B,R5 




JSR 


PC,XLT10 




MOV 


(SP) + ,R5 




MOV 


(SP) + f R4 




MOV 


(SP) + ,R3 




MOV 


(SP) + f R2 




MOV 


(SP) + ,R1 




MOV 


(SP) + ,R0 


.ENDM 






.MACRO 


WRTOUT 


A,B 




MOV 


R4,-(SP) 




MOV 


R5,-(SP) 




MOV 


CRTRAB,R4 




$STORE 


A,RBF,R4 




$STORE 


B,RSZ,R4 




MOV 


CRTLST,R5 




$PUT 






MOV 


(SP) + ,R5 




MOV 


(SP) + ,R4 


.ENDM 






.SBTTL 


MAIN PROGRAM 


.PAGE 






; INTERNAL SPACE POOL 


• EVEN 


POOL$B 






P$BDB 


2 



16-BIT NBR TO DECIMAL ASCII 
SAVE REGISTER ON STACK 
SAVE REGISTER ON STACK 
SAVE REGISTER ON STACK 
SAVE REGISTER ON STACK 
SAVE REGISTER ON STACK 
SAVE REGISTER ON STACK 
PUT IN NUMBER 

LOCATION OF 1ST BYTE RCV BFR 
TRANSLATE IT 

GET REGISTER BACK FROM STACK 
GET REGISTER BACK FROM STACK 
GET REGISTER BACK FROM STACK 
GET REGISTER BACK FROM STACK 
GET REGISTER BACK FROM STACK 
GET REGISTER BACK FROM STACK 



OUTPUT MSG AND LENGTH 

PUT RAB REFERENCE ON STACK 

OUT ARG LIST REF ON STACK 

PUT CRT RAB REFERENCE IN R4 

MSG NAME IN RAB FLD 

PUT MSG LENGTH IN RAB FLD 

PUT CRT ARG LIST IN R5 

WRITE MESSAGE TO CRT 

POP OFF ORIGINAL ARG LIST 

POP OFF ORIGINAL RAB REF 



.ifP^ ^IbR^ 



P$BUF 1024. 



; BEGIN INITIALIZATION 
; NBR = 
MAXBUF(1/SEQ)+MAXREL (0 )+ (2*MAXIDX (0 ) ) 



P$FAB 
P$RAB 
POOL$E 



2 
2 



; NBR = 

DOC-STREAM-SIZE + CRT-STREAMS-SIZE 

DOC-STREAM-SIZE = 

BKS(l) * (512*MBC(1)) * MBF(l) = 512 

CRT-STREAM-SIZE = 

BKS(l) * (512*MBC(1)) * MBF(l) = 512 
FAB FOR EACH FILE 
TWO SEQUENTIAL FILES 
END INITIALIZATION AREA 



RMS FUNCTIONS NEEDED 



ORG$ SEQ,<GET,PUT,FIN> ; SEQ FILE GETS, PUT, FINDS 
I!!!!!!!!!!!!!! R U N - T I M E !!!!!■!!!■■ i i i i i i i i i i i 



.EVEN 

START: $INIT 



; INITIALIZE RMS 
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$OPEN CRTFAB 
MOV CRTFAB, R4 
$COMPARE 0,STS,R4 
BGT 2$ 
JMP FILERR 

2$: $CONNECT CRTRAB 

MOV CRTRAB, R4 
$COMPARE 0,STS,R4 
BGT 4$ 
JMP FILERR 

4$: WRTOUT BGNMSG, BGNMSL 



OPEN CRT 

SET BLOCK TO LOOK AT 
CHECK OUT STATUS FIELD 
GO AROUND IF NO ERROR 
ERROR CODE(S) AND QUIT 

HOOK UP CRT 
SET BLOCK TO LOOK AT 
CHECK OUT STATUS FIELD 
GO AROUND IF NO ERROR 
ERROR CODE(S) AND QUIT 

OUTPUT IT 



$OPEN DOCFAB 
MOV DOCFAB, R4 
$COMPARE 0,STS,R4 
BGT 8$ 
JMP FILERR 



OPEN INPUT FILE 
SET BLOCK TO LOOK AT 
CHECK OUT STATUS FIELD 
GO AROUND IF NO ERROR 
ERROR CODE(S) AND QUIT 



8$: WRTOUT OPNMSG, OPNMSL 
$CONNECT DOCRAB 
MOV DOCRAB, R4 
$COMPARE 0,STS,R4 
BGT GETLIN 
JMP FILERR 



GETLIN: MOV 
MOV 
JSR 



DOCRAB, R4 
DOCLST,R5 
PC, INPUT 



HOOK UP INPUT FILE 
SET BLOCK TO LOOK AT 
CHECK OUT STATUS FIELD 
GO AROUND IF NO ERROR 
ERROR CODE(S) AND QUIT 

DOCERR GETS RIGHT CODE 

DOC FILE ARG LIST 

GET RECORD FROM DOC FILE 



RO = POINTER TO INPUT LINE 

Rl = CHARACTERS/WORD COUNTER (TO HANDLE MULTIPLE SPACES) 

R2 = WORDS/LINE COUNTER 

R3 = VECTOR OFFSET INTO TABLE 

R4 = DOCRAB 

R5 = DOCLST 



DOW OR D: 



CLR 
CLR 
INC 



Rl 
R3 
CHRCNT 



INITIALIZE CHAR/WORD COUNTER 
INITIALIZE VECTOR OFFSET 
CNT CHAR BEFORE LOOK AT IT 



CMP CHRCNT, RECLEN 
BGT 12$ 



PAST END OF INPUT RCD YET? 
IF SO, GO FINISH UP 



4$: CMPB CHCODE (R3) , 

BEQ 8$ 

TST (R3)+ 

CMP R3, CHCEND 

BLT 4$ 



(RO) ; CHECK ON NEXT CHAR IN LINE 

; PROCESSING IF EQUAL 

; INCREMENT VECTOR 

; NOT IN TABLE? 

; CHECK NEXT ONE 



8$: JSR 
INCB 



PC,@CHPRCS (R3) 
(R0) + 



DO RIGHT THING 

MOVE TO NEXT CHARACTER 
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BR 


DOW OR D 


12$: 


CMP 


0,R1 




BEQ 


16$ 




INC 


R2 


16$: 


CMP 


0,R2 




BEQ 


18$ 




ADD 


R2,WDCNT 




XLT210 


R2,WDMSG 




XLT210 


WDCNT,WDMSG+3 8 




WRTOUT 


WDMSG,WDMSL 




MOVWD 


BLKS3,WDMSG 


18$: 


JMP 


GETLIN 


SBTTL 


SUBROUTINES 


PAGE 







ANY CHARACTERS MOVED? 

NOT A REAL LAST WORD 

COUNT LAST WORD 

ANY WORDS IN THIS LINE? 

IF NOT, DON'T DO ANYTHING 

ADD THIS LINE TO TOTAL 

PUT CURRENT LINE IN MSG 

PUT TOTAL CURRENT IN MSG 

OUTPUT IT 

COVER UP LAST WORD COUNT 

GO BACK FOR NEXT LINE 



SUBROUTINES 



INPUT: $GET 

$COMPARE 0,STS,R4 
BGT 2$ 

JMP DOCERR 

2$: $COMPARE 0,RSZ,R4 
BEQ INPUT 

MOV RECLEN,R3 

$FETCH (R3),RSZ,R4 
BR 8$ 



GET RECORD FROM INPUT FILE 
CHECK OUT STATUS FIELD 
GO AROUND IF NO ERROR 
ERROR CODE(S) AND QUIT 

RECORD LENGTH =0? 

IF SO, GO GET ANOTHER ONE 

ADDRESS IN REGISTER 

XFR RCD LEN TO BBFR 

BYPASS WRITE OUT 



SPECIAL CASE OF WRTOUT HERE BECAUSE OF RECLEN 



6$: MOV R4,-(SP) 

MOV R5,-(SP) 

MOV CRTRAB,R4 

$STORE DOCRCD,RBF,R4 

$STORE RECLEN, RSZ,R4 

MOV CRTLST,R5 
$PUT 

MOV (SP) + ,R5 

MOV (SP) + ,R4 

8$: MOV DOCRCD,R0 

CLR R2 

CLR CHRCNT 

INC LINENO 

RTS PC 



PUT RAB REFERENCE ON STACK 
OUT ARG LIST REF ON STACK 
PUT CRT RAB REFERENCE IN R4 
PUT MSG NAME IN RAB FLD 
PUT MSG LENGTH IN RAB FLD 
PUT CRT ARG LIST IN R5 
WRITE MESSAGE TO CRT 
POP OFF ORIGINAL ARG LIST 
POP OFF ORIGINAL RAB REF 

ADDR OF 1ST CHAR TO RO 
INITIALIZE WORD COUNTER 
INITIALIZE CHAR COUNTER 
COUNT LINE/RECORD 



FFEED: INC PAGENO 

CLR LINENO 

XLT210 PAGENO, FFMSG+5. 

WRTOUT FFMSG,FFMSL 

MOV 5.,R3 
2$: $FIND 

$COMPARE 0,STS,R4 



ADD ONE TO PAGE NUMBER 
RESET LINE NUMBER 
TURN IT INTO DECIMAL 
ANNOUNCE FORM FEED 
FIND CTR TO TOP OF TEXT 
MOVE PAST A LINE 
CHECK OUT STATUS FIELD 
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4$: 



BGT 


4$ 


MOV 


(SP) + ,R0 


JMP 


DOC ERR 


SOB 


R3,2$ 


JSR 


PC, INPUT 


DECB 


RO 


CLR 


Rl 



RTS 



PC 



GO AROUND IF NO ERROR 

PULL RTN ADDR OFF STACK 

ERROR CODE(S) AND QUIT 

SUB ONE AND BRNCH IF <> 

READ NEXT RECORD 

FOR COMMON INCREMENT 

GET RID OF ANY RESIDUAL THAT 

CAN COUNT WORD 

PROCESS IT 



NOTSPA: 


INC 


Rl 


• 
/ 


RTS 


PC ; 


'HYFEN: 


CMP 


CHRCNT,RECLEN 




BNE 


NOTSPA 




MOV 


R2,-(SP) 




JSR 


PC, INPUT ; 
; (DON'T 
; SINCE I 




MOV 


(SP) + ,R2 




DECB 


RO ; 




CLR 


Rl 




RTS 


PC 



COUNT IT 

LOOK AT NEXT CHARACTER 



LAST CHARACTER IN LINE? 

TREAT IT LIKE ANY OTHER 

CIRCUMVENT INPUT 

BRING IT CONTINUATION LINE 
(DON'T WORRY ABOUT DOUBLE -SPACING 
SINCE INPUT THROWS AWAY BLANK LINE) 

BRING WORD COUNT BACK 

ANTICIPATE AUTO INCREMENT 

GET RID OF ANY RESIDUAL THAT 

CAN COUNT WORD 

PROCESS IT 



SPACE: CMP 

BEQ 

CLR 

INC 

4$: RTS 



0,R1 
4$ 
Rl 
R2 
PC 



ANY CHARACTERS MOVED? 

NONE WERE 

CLEAR CHAR/WORD COUNTER 

ONE MORE WORD 

DO NEXT ONE 



XLT8: 



MOV 

BIC 

ADD 

MOVB 

ASR 

ASR 

ASR 

SOB 



R1,-(SP) ; USE STACK AS SCRATCH PAD 

B1111111111111000,@SP ; CLR ALL BUT LAST 3 



'0,@SP 
(SP) + ,-(R2) 
Rl 
Rl 
Rl 
R0,XLT8 



CHANGE DIGIT TO ASCII 
MOVE CHARACTER INTO BUFFER 
3 PLACES TO THE RIGHT 



LOOP IF MORE DIGITS 



NOW CONVERT LEFTMOST BIT IN OCTAL NUMBER 





BIC 


Bllllllll 




ADD 


'0,R1 




MOVB 


R1,-(R2) 




RTS 


PC 


XLT10: 


MOV 


XLTBUF,R4 


2$: 


TST 


(R4) 




BEQ 


4$ 




CMP 


RO, (R4)+ 




BHIS 


2$ 



GET BIT 15 



CONVERT 
MOVE TO 
GO BACK 



TO ASCII 
BUFFER 



POINT TO POWERS OF 

END OF TABLE? 

YES 

START YET? 

NO 



10 
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TST 


"(R4) 


4$: 


TST 


-(R4) 




BNE 


6$ 




MOVB 


'0, (R5)+ 




BR 


10$ 


6$: 


MOV 


R0 f R3 


8$: 


CLR 


R2 




DIV 


(R4) ,R2 




ADD 


•0,R2 




MOVB 


R2, (R5)+ 




TST 


-(R4) 




BNE 


8$ 


10$: 


RTS 


PC 


SBTTL 


ERROR 


ROUTINES 


PAGE 






ERROR 


ROUTINES 



BACK UP TABLE 

DITTO 

NON-ZERO NUMBER TO PRINT 

PRINT A ZERO 

ALL DONE 

MOVE NBR IN PREP FOR DIVIDE 

MORE PREP FOR DIVIDE 

DIVIDE BY POWER OF 10 

MAKE QUOTIENT A CHARACTER 

INSERT IN RCV BUFFER 

GET ANOTHER POWER OF 10 

NO THRU YET 

GO HOME WHEN DONE 



ERROR ROUTINE FOR FILE OPERATIONS AND DOC FILE AND CRT 



FILERR; 
FILER1: 



4$: 



MOVWD 

$FETCH 

XLT28 

WRTOUT 

$COMPARE 

BEQ 

MOVWD 

$FETCH 

MOV 

XLT28 

WRTOUT 

MOV 

MOV 

CLR 

SOB 



.LIST ME 

XLT210 
•NLIST ME 

WRTOUT 
DUN: EXIT$S 



FILID, ERRMSG 
R2,STS,R4 
R2,ERRNBR 
ERRMSG,ERRMSL 

0,STV,R4 
DUN 

STVID, ERRMSG 
R2,STV,R4 
R2,-(SP) 
R2,ERRNBR 
ERRMSG, ERRMSL 

(SP)+,R2 
6. ,R0 

(R0) + 
R0,4$ 

R2,ERRNBR 

ERRMSG, ERRMSL 



MOVE ERROR CODE IN 

FIGURE NBR; PUT IT IN BFR 

PUT IT OUT 

ANYTHING IN STV? 

GO AROUND IF THERE'S NOT 

MOVE COMPLETION VALUE IN 
SO NO NEED FETCH IT AGN 
FIGURE NBR; PUT IT IN BFR 

BRING BACK STV VALUE 
NBR OF CHAR IN ERRNBR 
ZERO THAT BYTE 
TILL ALL ARE DONE 

MAKE IT A DECIMAL NUMBER 

DISPLAY IT 
QUIT THIS THING 



ERROR ROUTINE FOR RECORD OPERATION ON INPUT FILE 



DOC ERR: $COMPARE ER$EOF, STS, R4 
BEQ 2$ 

$COMPARE ER$RTB,STS,R4 
BEQ 4$ 

MOVWD DOC ID, ERRMSG 
JMP FILER1 

2$: XLT210 WDCNT,WDMSG+3 8. 
WRTOUT WDMSG+2 4 . , 1 8 . 
WRTOUT ENDMSG,ENDMSL 
BR 32$ 



IT 



IT 



RUN OUT OF RECORDS? 

GO AROUND IF THAT'S 

LINE TOO LONG? 

GO AROUND IF THAT'S 

IDENTIFY ERROR 

HANDLE LIKE OTHER ERRORS 

PUT TOTAL CURRENT IN MSG 

OUTPUT IT 

PUT IT ON SCREEN 

GO TO END 
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4$: XLT210 


LINENO,LINMSG+5 


WRTOUT 


LINMSG, LINMSL 


JMP 


INPUT 


32$: EXIT$S 




.END START 





PUT IN LINE NUMBER 
DISPLAY MSG 

GET NEXT RECORD (PC IS GOOD 
•CAUSE NOT LEFT SUBRTN) 
QUIT IT 
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B.3 TESTING RELATIVE FILE CAPABILITIES 



This sample program creates a Relative file, sets up a Record Access 
Stream, and runs five tests: 

1. Test if can put a record with a relative record number greater 
than the Maximum Record Number set for the file. 

2. Test if can get records past the Maximum Record Number set for the 
file. 

3. Test if sequential get operations retrieve only valid records. 

4. Test if sequential get operations retrieves deleted records. 

5. Test if approximate match tests (KGE and KGT) work during random 
get operations. 

.MCALL $INIT, FAB$B , NAM$B , XAB$B , RAB$B , ORG$ , POOL$B 
.MCALL $GNCAL, $FBCAL, $RBCAL, $STGDPLY, $GETSTG, EXIT$S 



$GNCAL 






$FBCAL 






$RBCAL 






; POOL 


SPACE 




POOLAR: 


POOL$B 






P$BDB 


6 




P$FAB 


2 




P$RAB 


2 




P$BUF 


4608. 




POOL$E 




; FAB 


AREA 
.EVEN 




FABAR: 


FAB$B 






F$BKS 


2 




F$FAC 


FB$GET 




F$FOP 


FB$TMD 




F$LCH 


1 




F$MRS 


80. 




F$ORG 


FB$REL 




F$RFM 


FB$VAR 




FAB$E 




; RAB AREA 






• EVEN 




RABAR: 


RAB$B 






R$FAB 


FABAR 




R$KBF 


KEYNO 




R$KSZ 


4 




R$RAC 


RB$SEQ 



;ALLOCATE FAB 

; BUCKET SIZE 
FB$GETIFB$PUT!FB$DEL ;D0ING GETS AND PUTS 

THIS FILE TO BE DELETED 
USE LOGICAL CHANNEL 1 
MAX RECORD SIZE OF 80 
RELATIVE FILE 
VARIABLE LENGTH RECORDS 



;ALLOCATE RAB 

; POINTS TO FAB AREA 

;WHERE TO PUT RELATIVE KEY NUMBER 

;KEY IS 4 BYTES 

;WRITE RECORDS SEQUENTIALLY 



B-14 Sample RMS-11 Programs 



R$RBF 


RECBUF 


R$UBF 


RECBUF 


R$USZ 


150. 


RAB$E 





;ADDR OF RCD PUT OR GOT 
/SAME AS RBF 



.EVEN 



FABTI: 


FAB$B 






F$FAC 


FB$PUT 




F$FNA 


TFNAM 




F$FNS 


TFNAMS 




F$FOP 


FB$CTG!FB$TMD 




F$LCH 


2 




F$MRS 


768. 




F$ORG 


FB$SEQ 




F$RAT 


FB$CR 




F$RFM 


FB$FIX 




FAB$E 




RABTI: 


RAB$B 






R$FAB 


FABTI 




R$RAC 


RB$SEQ 




R$UBF 


BUFTI 




R$USZ 


80. 




RAB$E 




; LOCAL 


SYMBOLS 




CR = 15 






LF = 12 




PRAMTR : 


.BLKW 1 




HOLDIT: 


.BLKB 


2 


KEYNO: 


.BLKB 


4 


KEYTST: 


.BLKB 


2 


WITH RECORD PUT 


DELTST: 


.BLKB 


2 


TSTFOR: 


.BLKB 


1 


ERR: 


.BLKB 


1 


RNFSET: 


.BLKB 


1 


} 


.EVEN 





PUT TO THE FILE 

TERMINAL FILE NAME 

TERMINAL FILE NAME SIZE 

CONTIGUOUS SPACE, TEMP FILE 

LOGICAL CHANNEL 2 

MAX REC SIZE = 768. BYTES 

SEQUENTIAL FILE 

RECS DELIMITED BY CR AND LF 

FIXED FORMAT RECS 



FILE CTRL BLOCK ADDR 
SEQUENTIAL ACCESS 
USER BUFFER ADDR 
MAX SIZE = 80. BYTES 



;ASCII CARRIAGE RETURN 
;ASCII LINE FEED 

; PARAMETER TO SEND INFO TO PRINT 

;HOLD NUMBER FOR ASCII CONVERT 

; RELATIVE KEY 

; KEYTST TO COMPARE RECORD RETRIEVED 



TEST FOR DELETED RECORDS 
TO TEST FOR FOURTH TEST 
TEST FOR TEST 4 ERRORS 
TEST FOR RNF ERROR 



BUFTI: 



.BLKB 



80, 



;TERMINAL FILE BUFFER 



RECBUF: 
RECKEY: 

RECLEN = 



BLKW 2 

ASCII /MISC. DATA/ <CRXLF> 
, - RECBUF 



TFNAM: .ASCII /TI : RELTST. ERR/ ; TERMINAL FILE NAME 
TFNAMS = . - TFNAM 
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MSGTBL: 

r 

ERRl: .ASCII /ERROR CREATING TTY FILE/ <CRXLF> 

ERR1LN = . - ERRl 

! 

ERR2: .ASCII /ERROR CONNECTING TTY FILE/ <CRXLF> 

ERR2LN = . - ERR2 

ERR3: .ASCII /ERROR CREATING RELATIVE FILE/ <CRXLF> 

ERR3LN = . - ERR3 

i 

ERR4: .ASCII /ERROR CONNECTING RELATIVE FILE/ <CRXLF> 

ERR4LN = . - ERR4 

/ 

MSG5: .ASCII /TEST / 

TESTNO: .BLKB 2 

SUC5: .ASCII / SUCCESSFUL!/ <CRXLF> 

MSG5LN = . - MSG5 

ERR6: .ASCII /ERROR PUTTING RECORD TO FILE/ <CRXLF> 

ERR6LN = . - ERR6 

} 

ERR7: .ASCII /ERROR DELETING RECORD NUMBER / 

DELNUM: .BLKB 4 

.ASCII <CRXLF> 
ERR7LN = . - ERR7 

ERR8: .ASCII /ERROR GETTING RECORD FROM FILE/ <CRXLF> 
ERR8LN = . - ERR8 

ERR9: .ASCII /ERROR CLOSING FILE/ <CRXLF> 
ERR9LN = . - ERR9 

ERR10: .ASCII /ERROR REWINDING FILE/ <CRXLF> 
ER10LN = . - ERR10 

ERR11: .ASCII /ERROR DISCONNECTING FILE/ <CRXLF> 
ER11LN = . - ERR11 

i 

ERR12: .ASCII /RETRIEVED WRONG RECORD IN FILE/ <CRXLF> 
ER12LN = . - ERR12 

ERR13: .ASCII /ERROR FINDING RECORD NUMBER / 
FINDNO: .BLKB 4 
CRLF13: .ASCII <CRXLF> 
ER13LN = . - ERR13 

ERR14: .ASCII /ERROR - OVER 40. RECORDS WRITTEN ON TEST1/ <CRXLF> 
ER14LN = . - ERR14 

ERR15: .ASCII /DID NOT GET RECORD NUMBER / 
TST5NO: .WORD 1 
CRLF15: .ASCII <CRXLF> 
ER15LN = . - ERR15 

• 
9 

ERR16: .ASCII /ERROR DISCONNECTING FILE/ <CRXLF> 
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ER16LN = . - ERR16 



.EVEN 




ERRTBL: .WORD 


ERR1 


.WORD 


ERR1LN 


.WORD 


ERR2 


.WORD 


ERR2LN 


.WORD 


ERR3 


.WORD 


ERR3LN 


.WORD 


ERR4 


.WORD 


ERR4LN 


.WORD 


MSG5 


.WORD 


MSG5LN 


.WORD 


ERR6 


.WORD 


ERR6LN 


.WORD 


ERR7 


.WORD 


ERR7LN 


.WORD 


ERR8 


.WORD 


ERR8LN 


.WORD 


ERR9 


.WORD 


ERR9LN 


.WORD 


ERR10 


.WORD 


ER10LN 


• WORD 


ERR11 


.WORD 


ER11LN 


.WORD 


ERR12 


.WORD 


ER12LN 


.WORD 


ERR13 


.WORD 


ER13LN 


.WORD 


ERR14 


.WORD 


ER14LN 


.WORD 


ERR15 


.WORD 


ER15LN 


.WORD 


ERR16 


.WORD 


ER16LN 


ORG$ 


REL,<CRE,FIN,GET,PUT,DEL 


ORG$ 


SEQ,<CRE,PUT> 


START: 





$INIT 





JSR 


PC,CRETTY 




JSR 


PC , CREATE 


1 


JSR 


PC,TEST1 


1 


JSR 


PC,TEST2 




JSR 


PC, CLOSE 




JSR 


PC,TEST3 




JSR 


PC,TEST4 




JSR 


PC,TEST5 



CREATE, CONNECT TTY FILE 

CREATE, CONNECT RELATIVE FILE 

TEST 1 BEGINS 

TEST 2 BEGINS 

DISCONNECT AND CLOSE FILE 

TEST 3 BEGINS 

TEST 4 BEGINS 

TEST 5 BEGINS 
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JSR PC, CLOSE 
EXIT$S 

CREATE AND CONNECT THE TTY FILE 



DISCONNECT AND CLOSE PILE 



CRETTY: 



MOV 

$CREATE 

MOV 

$CONNECT 

RTS 



, PRAMTR 
FABTI, ENDIT 
4, PRAMTR 
RABTI, ENDIT 
PC 



;SET UP TTY CREATE ERRMSG 
;CREATE TTY FILE 
;SET UP TTY CONNECT ERR 
;CONNECT TTY FILE 



; CREATE 


THE RELATIVE FILE 


CREATE: 








MOV 


RABAR, R4 




$STORE 


RECLEN,RSZ,R4 




CLR 


Rl 




MOV 


40. ,R0 




MOV 


FABAR,R5 




$STORE 


R0,MRN,R5 




MOV 


10, PRAMTR 




$CREATE 


R5, ENDIT 




RTS 


PC 


CONECT: 








MOV 


14, PRAMTR 




MOV 


RABAR,R5 




$CONNECT R5, ENDIT 




RTS 


PC 



INITIALIZE RAB POINTER 

SET UP RECORD SIZE 

RO Rl SET UP 2 WORD MRN 

SET UP RO FOR MRN 

SET UP FAB POINTER 

INITIALIZE 40. AS MRN 

SET UP CREATE REL FILE ERR 

CREATE THE FILE 



;SET UP CONNECT REL FILE ERR 
;SET UP RAB POINTER 
/CONNECT REL FILE 



REWIND THE FILE 



REWIND: 



MOV 44, PRAMTR 

SREWIND RABAR, ENDIT 

RTS PC 

DISCONNECT AND CLOSE THE FILE 



;SET UP FOR REWIND ERROR 
;GO TO B-O-F FOR NEXT TEST 



CLOSE: 



MOV 74, PRAMTR ;SET UP FOR DISCONNECT ERROR 
$DISCQNNECT RABAR, ENDIT /DISCONNECT FILE 

;SET UP FOR CLOSE ERROR 

;CLOSE FILE 





MOV 


40, PRAMTR 




$CLOSE 


FABAR, ENDIT 




RTS 


PC 


; PR INT 


THE MESSAGES 


PRINT: 








MOV 


0,R2 




MOV 


PRAMTR, R2 




ADD 


ERRTBL,R2 




MOV 


RABTI, R3 




$STORE 


(R2) ,RBF,R3 




$STORE 


2(R2) ,RSZ,R3 



; CLEAR R2 

;SET UP INDEX WITHIN TABLE 
; POINTER TO ERROR MESSAGE 
; POINTER TO ERROR TABLE 
; STORE ADDRESS OF MESSAGE 
; STORE SIZE OF MESSAGE 
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$PUT 
RTS 



R3,B0MB 
PC 



;TTY MSG - BOMB ON ERROR 



ENDIT: 



JSR 



PC, PRINT 



; PR INT ERROR MESSAGE 



BOMB: 



BPT 



;BOMB 



TEST 1 



TEST1: 



PUT IT: 



T1ERR; 



THIS IS A TEST OF MRN. MRN SET TO 40. 
WILL ATTEMPT TO WRITE 50. RECORDS. 
SHOULD ENCOUNTER ER$MRN ERROR. 



CLR 
JSR 



Rl 

PC, CONECT 



INC Rl 

$PUT R4 

$COMPARE SU$SUC,STS,R4 

BNE T1ERR 

CMP 50., Rl 

BHI PUTIT 

MOV 64,PRAMTR 

JSR PC, ENDIT 

MOV 24,PRAMTR 
$COMPARE ER$MRN,STS,R4 

BNE ENDIT 
MOV 20,PRAMTR 
MOV 61,TESTNO 

JSR PC, PRINT 

JSR PC, REWIND 

RTS PC 



INITIALIZE Rl 
;CONNECT THE FILE 



NEXT RECORD 
WRITE THE RECORD 
PUT ERROR? 
IF YES, GO TO T1ERR 
WRITTEN 50 RECORDS YET? 
NO, GO WRITE SOME MORE 
SET UP FOR TEST 1 ERROR 
;PRINT ERROR MESSAGE, BOMB 

SET UP FOR PUT ERROR 

MRN ERROR? 

NOT MRN ERROR — BOMB 

SET UP FOR SUCCESS MSG 

SET UP FOR PRINTING TEST 1 

;PRINT SUCCESS MESSAGE 

;RETURN TO B-O-F 

;GO ON TO TEST 2 



IF TEST 1 IS SUCCESSFUL, RECORDS HAVE BEEN WRITTEN 
UP TO MRN. THAT IS, 40 RECORDS HAVE BEEN WRITTEN. 
THE FILE HAS BEEN REWOUND, READY FOR TEST 2. 



TEST 2 



THIS TEST ATTEMPTS TO RETRIEVE RECORDS 

SEQUENTIALLY BEYOND MRN. 

SHOULD ENCOUNTER AN ER$EOF ERROR. 

IT ATTEMPTS TO RETRIEVE 50.. RECORDS. 

AFTER THE 40. TH RECORD, AN ER$EOF ERROR 

SHOULD RESULT. 



TEST2: 
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T2INC 



MOV 


RABAR, R4 


CLR 


Rl 


MOV 


34, PR AM TR 


MOV 


62,TESTNO 


INC 


Rl 


$GET 


RABAR 


$COMPARE SU$SUC,STS,R4 


BNE 


GETERR 


CMP 


50. ,R1 


BNE 


T2INC 


RTS 


PC 



GETERR: 



$COMPARE ER$EOF,STS,R4 

BNE ENDIT 

MOV 20,PRAMTR 

JSR PC, PRINT 

JSR PC, REWIND 

RTS PC 



SET UP RAB POINTER 
INITIALIZE RECORD COUNTER 
SET UP FOR GET ERROR 
SET UP FOR PRINTING TEST 2 

INCREMENT RECORD COUNTER 

GET ANOTHER RECORD 

SUCCESSFUL GET? 

IF NOT, GO TO GETERR 

GOTTEN 50 RECORDS YET? 

IF NOT, CONTINUE 

;YES, RETURN 

;EOF ERROR? 

;NOT AN EOF ERROR - BOMB 

;SET UP FOR TEST SUCCESS MESSAGE 
PRINT SUCCESS MESSAGE 
GO TO BEGINNING OF FILE 
GO ON TO NEXT TEST 



TEST 3 



TEST3: 



JSR 


PC, CREATE 


$STORE 


RB$KEY,RAC,R4 ; 


JSR 


PC,CONECT 


MOV 


l,KEYNO 


CLR 


KEYNO+2 ; 


CLR 


RECKEY+2 



CREATE A NEW FILE. 

PUT EVERY OTHER RECORD RANDOMLY UP TO AN MRN OF 40. 

REWIND, AND GET SEQUENTIALLY. 

SHOULD GET ONLY THOSE RECORDS JUST PUT. 



;CREATE NEW RELATIVE FILE 
RELATIVE ACCESS MODE 
;CONECT THE FILE 
INITIALIZE THE RELATIVE KEY 
CLEAR 2ND WORD OF KEY 
CLEAR 2ND WD OF KEY IN FILE 



SET UP FOR PUT ERROR 
PUT KEY NUMBER IN RECORD 
PUT RCD; ERROR = MSG, END. 
SKIP A RECORD 
FILE FULL? 

IF NOT, WRITE SOME MORE 
SET UP FOR TEST 3 SUCCESS 
SET UP FOR PRINTING TEST 3 



******** COMMON ROUTINE FOR TESTS 3 AND 4 ********** 



REWIND AND REINITIALIZE 



;SET UP 


FILE - 


- WRITE EVERY OT 


SETUP: 








MOV 


24,PRAMTR 




MOV 


KEYNO,RECKEY 




$PUT 


RABAR, ENDIT 




ADD 


2,KEYNO 




CMP 


40. ,KEYNO 




BHI 


SETUP 




MOV 


20,PRAMTR 




MOV 


63,TESTNO 



SEQGET: 



CALL REWIND 
MOV -1,KEYTST 
$STORE RB$SEQ,RAC,R4 



;RETURN TO BEGINNING OF FILE 
;SET UP TO TEST FOR CORRECT RCD 
;GET SEQUENTIALLY 
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GET THE RECORDS SEQUENTIALLY 



GETIT: 



$GET R4 

$COMPARE SU$SUC,STS,R4 

BNE GETERR 



RECTST: 








ADD 


2,KEYTST 




CMP 


KEYTST,RECKEY 




BEQ 


GETIT 


B ADR EC: 








CMPB 


l,TSTFOR 




BNE 


B ADC ON 




ADD 


6,DELTST 




CMP 


DELTST,KEYTST 




BEQ 


RECTST ; 


B ADC ON: 








MOV 


54, PR AM TR 




JMP 


ENDIT ; 



GET RECORD 
SUCCESSFUL GET? 
IF NOT, TEST FOR E-O-F 
GETERR IN TEST 2 

EVERY OTHER RECORD 

RIGHT RECORD? 

IF SO, LET'S GET ANOTHER 

IS IT TEST 4? 

IF NOT, WRONG RCD 

HOLD KEY OF NXT DELETED RCD 

IS IT A DELETED RECORD? 

YES, ADD 2 TEST AGAIN 

;WRONG RECORD = MSG 

; PR INT OUT MESSAGE, BOMB 



TEST 4 



TEST 4 USES THE FILE CREATED IN TEST 3. 
SOME RECORDS ARE DELETED. 

GET SEQUENTIALLY AND SEE IF DELETED RECORDS 
ARE FOUND. 



TEST4; 



NXTDEL: 



GET4: 



MOV 


RABAR,R4 


$STORE 


RB$KEY,RAC,R4 


MOV 


-5,KEYNO 


MOV 


l,TSTFOR 


MOV 


-5,DELTST 


ADD 


6,KEYNO 


JSR 


PC,FINDIT 


CMP 


37. ,KEYNO 


BHI 


NXTDEL 


CMPB 


0,ERR 


BEQ 


GET4 


JMP 


BOMB 


MOV 


20, PR AM TR 


MOV 


64,TESTNO 


JSR 


PCSEQGET 


RTS 


PC 



FINDIT: 



$FIND RABAR 

$COMPARE SU$SUC,STS,R4 
BEQ DELETE 

MOV 60,PRAMTR 

MOV KEYNO,R0 



SET UP RAB POINTER 
DELETE USING RANDOM 
INIT REL KEY FOR DELETES 
SET UP FOR FOURTH TEST 
INIT FOR DELETED RCD KEY 

;DELETE EVERY 4TH RECORD 

;GO DELETE IT 
;LAST RECORD 

;TO BE DELETED BEFORE EOF? 
;IF NOT, DELETE SOME MORE 
;ANY ERRORS ENCOUNTERED? 
;NO ERRORS, GET SEQUENTIALLY 
; ERRORS FOUND - BOMB 

;SET UP FOR TEST 4 SUCC MSG 
;SET UP FOR PRINTING TEST 4 

;READY TO GET SEQUENTIALLY 

;GO ON TO NEXT FILE 



FIND SUCCESSFUL? 
IF IT WAS, DELETE RECORD 
SET UP FOR FIND ERROR 
SET UP FOR KEY NO. 



,-CONVERSION TO ASCII 



JSR 



PC,CONVER 



;CONVERT RCD NBR TO ASCII 
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DELETE: 



MOV HOLDIT,FINDNO 

JSR PC, PRINT 

RTS PC 



$DELETE RABAR 
$COMPARE SU$SUC,STS,R4 



BEQ 


RETURN 


MOV 


30, PRAM TR 


MOV 


KEYNO,R0 


CALL 


CONVER 


MOV 


HOLDIT,DELNUM 


JSR 


PC, PRINT 


RETURN: 




RTS 


PC 


/CONVERSION TO 


ASCII TO PRINT 


CONVER: 




MOVB 


1,ERR 


MOV 


RABAR, R4 


$STORE 


1,STS,R4 


MOV 


1,R3 


MOV 


2,R2 



;PUT RCD NBR IN ERRMSG 
; PR INT ERROR MESSAGE 
;GO ON TO NEXT RECORD 



DELETE RECORD 

SUCCESSFUL DELETE? 

IF SUCCESSFUL, CONTINUE 

SET UP FOR DELETE ERRMSG 

SET UP FOR ASCII CONVERT 

CNV KEY NBR TO ASCII FOR ERRMSG 

PUT RCD NBR IN ERRMSG 

; PR INT ERROR MESSAGE 



;GO ON TO NEXT RECORD 



NOTE THAT ERROR OCCURRED 
SET UP RAB PNTR AFTER ERR 
RESET TO GOOD STATUS 
SET UP R3 FOR INDEXING 
SET UP R2 TO LOOP 2 TIMES: 



;ONCE FOR EACH BYTE 



LOOP: 



MOV 


R0,-(SP) 


BIC 


-10, RO 


ADD 


60, RO 


MOVB 


R0,HOLDIT(R3) 


MOV 


(SP) + ,R0 


ASR 


RO 


ASR 


RO 


ASR 


RO 


DEC 


R3 


SOB 


R2,LOOP 


RTS 


PC 



;SAVE REMAINDER FOR CNV 

;CLEAR ALL BUT LOW ORDER 3 BITS 

; CONVERT TO ASCII 

; STORE IT IN RECORD 

;GET COUNTER 

; SHIFT RIGHT 3 BITS 

;TO WORK ON EACH DIGIT 

;MOVE TO NXT BYTE OF RECKEY 
;DIGIT IN EACH BYTE?? 



TEST 5 



THIS TEST WILL TEST THE ROP FIELDS OF 
KGT AND KGE. 

AFTER SUCCESSFUL COMPLETION OF TEST 4, 
THE FILE WILL NOW HAVE OCTAL RECORDS: 
3,5,11,13,17,21,25,27,33,35,41,43,47. 
USING THIS INFORMATION, WE WILL TEST 
■KEY GREATER THAN' AND 'KEY GREATER THAN 
OR EQUAL TO' . 



TEST5: 



MOV 


RABAR, R4 


$STORE 


RB$KEY,RAC,R4 


$STORE 


RB$KGT,ROP,R4 


JSR 


PC , KGT 


$STORE 


RB$KGE,ROP,R4 



SET UP RAB POINTER 
USING RANDOM 
SET UP KEY GREATER THAN 
DO KEY GREATER THAN TEST 
SET UP KEY GTR'N OR = TO 
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■■ii 



GOOD 5: 



KGT: 



KGE 



GET5: 



JSR 


PC, REWIND 


JSR 


PC, KGE 


CMPB 


0,ERR 


BEQ 


GOOD5 


RTS 


PC 


MOV 


65,TESTNO 


MOV 


20,PRAMTR 


CALL 


PRINT 


RTS 


PC 


MOV 


5,KEYNO 


MOV 


11,R0 


JSR 


PC,GET5 


MOV 


20,KEYNO 


MOV 


21, RO 


CALL 


GET5 


MOV 


27, KEYNO 


MOV 


33, RO 


JSR 


PC,GET5 


MOV 


47, KEYNO 


MOVB 


1,RNFSET 


JSR 


PC, GETS 


RTS 


PC 


MOV 


5, KEYNO 


MOV 


5,R0 


JSR 


PC,GET5 


MOV 


20, KEYNO 


MOV 


21, RO 


CALL 


GET5 


MOV 


27,KEYNO 


MOV 


27, RO 


CALL 


GET5 


MOV 


47, KEYNO 


MOV 


47, RO 


JSR 


PC,GET5 


RTS 


PC 



$GET R4 

$COMPARE SU$SUC,STS,R4 

BEQ COMPAR 

CMPB 1,RNFSET 

BNE GT5ERR 

MOVB 0,RNFSET 

$COMPARE ER$RNF,STS,R4 





BNE 


GT5ERR 




RTS 


PC 


GT5ERR: 








MOV 


34, PR AM TR 




$STORE 


1,STS,R4 




MOVB 


1,ERR 




JSR 


PC, PRINT 




RTS 


PC 


COMPAR: 








CMP 


R0,RECKEY 




BNE 


ERROR 5 



;GO TO BEGINNING OF FILE 
DO KEY GTR'N OR = TEST 
ANY ERRORS DETECTED? 
NO ERRORS = SUCCESS MSG 



MOV 5 INTO SUCCESS MESSAGE 
SET UP FOR TEST 5 SUCC MSG 
PRINT MESSAGE 
;DONE WITH TEST 5 

WE WANT THE NEXT REC GT 5 

IT SHOULD BE RECORD 11 

GET THE RECORD 

TRY NEXT REC GTR'N 20 

WE SHOULD GET RECORD 21 

GET THE RECORD 

WANT THE NEXT REC GTR'N 27 

WE SHOULD GET RECORD 33 

GET THE RECORD 

GET REC GT 47 

SET UP TO TEST FOR RNF 

SHOULD GET RNF ERROR 

;GO ON TO KGE TEST 

WE WANT THE REC. GE 5 

SHOULD GET RECORD 5 

GET THE RECORD 

WE WANT THE REC. GE 20 

WE SHOULD GET RECORD 21 

GET THE RECORD 

WE WANT THE REC. GE 27 

SHOULD GET RECORD 27 

GET THE RECORD 

WE WANT THE REC. GE 47 

SHOULD GET RECORD 47 

GET THE RECORD 

;DONE WITH TEST 5 

GET THE RECORD 
SUCCESSFUL GET? 
YES = TEST FOR CORRECT RCD 
TESTING FOR RNF ERROR? 
NO = CONT ERR PROCESSING 
RESET FOR NO RNF ERROR 
DID WE GET AN RNF ERROR? 
NO, THERE'S REALLY AN ERROR 
;RNF ERR = GOOD, CONTINUE 

SET INDEX FOR GET ERR 
RESET TO GOOD STATUS 
SET ERR BYTE 
;PRINT GET ERROR MESSAGE 



;CORRECT RECORD? 

;IF NOT GO TO ERROR ROUTINE 
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ERR0R5: 



RTS PC 

MOV 70,PRAMTR 

JSR PC,CONVER 

MOV HOLDIT,TST5NO 

CALL PRINT 

RTS PC 



;WE DID, CONTINUE 

SET INDEX IN TABLE FOR ERROR MSG 
CNV RCD NBR TO ASCII FOR PRINT 
PUT RCD NBR IN MSG 
PRINT THE MESSAGE 



. END START 
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APPENDIX C 
DATE CONVERSION ROUTINE 



.TITLE $CDTTA - CONVERT DATE AND TIME TO ASCII 
.IDENT "X0001" 

COPYRIGHT (C) 1977 BY DIGITAL EQUIPMENT CORPORATION, 
COPYRIGHT (C) 1976 BY DIGITAL EQUIPMENT CORPORATION, 
MAYNARD, MASSACHUSETTS 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A 
SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE IN- 
CLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR 
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DIGITAL. 

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITH- 
OUT NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY 
DIGITAL EQUIPMENT CORPORATION. 

DIGITAL EQUIPMENT CORPORATION ASSUMES NO RESPONSIBILITY FOR 
THE USE OR RELIABILITY OF ITS SOFTWARE ON EQUIPMENT WHICH IS 
NOT SUPPLIED BY DIGITAL. 

ANDREW C. GOLDSTEIN 20 JUN 76 14:12 



SMACIT 

.MACRO 

JSR 

.ENDM 



$SAVRG 

R5,$SAVRG 

$SAVRG 



.MACRO 

$$$B1=0 

$$$B2=0 

$$$B3=0 

$$$B4=0 

$$$B5=0 

$$$B6=0 

$$$B7=0 

$$$B8=0 



.QUAD 



WORD 



.IRPC D,WORD 

$$$B1=$$$B1*10.+D' . 

$$$C=$$$Bl/256. 

$$$B1=$$$B10377 

S$$B2=$$$B2*10.+$$$C 

$$$C=$$$B2/256. 

$$$B2=$$$B20377 

$$$B3=S$$B3*10.+$$$C 

$$$C=$$$B3/256. 

$$$B3=$$$B30377 

$$$B4=$$$B4*10.+$$$C 

$$$C=$$$B4/256. 

$$$B4=$$$B40377 

$$$B5=$$$B5*10.+$$$C 

$$$C=$$$B5/256. 

$$$B5=$$$B50377 

$$$B6=$$$B6*10.+$$$C 

$$$C=$$$B7/256. 

$$$B6=$$$B60377 

$$$B7=$$$B7*10.+$$$C 

$$$C=$$$B7/256. 

$$$B7=$$$B70377 

$$$B8=$$$B8*10.+$$$C 

$$$C=$$$B8/256. 

$$$B8=$$$B80377 

.ENDM 

$$$W1=$$$B2*2 56.+$$$B1 

$$$W2=$$$B4*256.+$$$B3 

$$$W3=$$$B6*256.+$$$B5 

$$$W4=$$$B8*256.+$$$B7 

.LIST MEB 

•WORD $$$W1,$$$W2 

.WORD $$$W3,$$$W4 

.NLIST MEB 

. ENDM . QUAD 



SOME CONSTANTS 





.RADIX 


10 


QNS: 


.QUAD 


10000000 




.WORD 


$$$W1,$$$W2 




. WORD 


$$$W3,$$$W4 


QND: 


.QUAD 


864000000000 ; 




.WORD 


$$$W1,$$$W2 




.WORD 


$$$W3,$$$W4 


FDAYS 


= 365*4+1 




CDAYS 


= FDAYS *2 5-1 \ 


QDAYL 


= 15025 




QDAYH 


= 2 




DS15L 


= 65176 




DS15H 


= 1 





TENTHS OF MICROSECONDS IN A SECOND 



TENTHS OF MICROSECONDS IN A DAY 



NUMBER OF DAYS IN 4 YEARS 

AND NUMBER OF QUARTER DAYS IN A YEAR 

NUMBER OF DAYS IN A CENTURY 

NUMBER OF DAYS IN QUADRICENTURY, LOW 

NUMBER OF DAYS IN QUADRICENTURY, HI 

NUMBER OF DAYS BETWEEN l-JAN-1501 

AND 17-NOV-1858, LOW AND HIGH 



C-2 Date Conversion Routine 



.RADIX 



*** _ $CDTTA CONVERT DATE/TIME TO ASCII 

THIS ROUTINE CONVERTS THE STANDARD DATE/TIME REPRESENTATION INTO 
AN ASCII STRING. THE FORMATTING OF THE STRING IS CONTROLLED BY 
OPTION BITS ON INPUT. 

INPUTS: 

RO = ADDRESS TO STORE ASCII STRING 
Rl = ADDRESS OF 64 BIT DATE/TIME 
R2 = OPTION FLAGS: 

BIT = 1 IF DATE NOT WANTED 

BIT 1 = 1 IF TIME NOT WANTED 

BIT 2 = 1 IF TIME WANTED IN AM/PM 

BIT 3 = 1 IF SECONDS NOT WANTED 

OUTPUTS: 

RO UPDATED TO END OF GENERATED STRING 
OTHER REGISTERS PRESERVED 

THE DATE ALGORITHM BELOW ACCOUNTS FOR THE COMMON LEAP YEAR CYCLES - 
EVERY FOURTH YEAR IS, EXCEPT EVERY 100TH ISN'T, EXCEPT EVERY 400TH 
IS. YEAR 2000 IS A LEAP YEAR. THE CODE IS BASED ON ALGORITHMS 
WRITTEN BY P.CONKLIN, J.BARNABY, D.ROSENBERG, AND M.SPEIR. 



$CDTTA: 



$SAVRG 




MOV 


R1,-(SP) 


MOV 


R2,-(SP) 


MOV 


R0,R5 


SUB 


#16. ,SP 


MOV 


SP,R3 


ADD 


#8. ,R3 


MOV 


#QND,R0 


MOV 


SP,R2 


JSR 


PC,$DIVQ 



SAVE ALL REGISTERS 

ALLOCATE TWO QUAD SLOTS 

SPLIT DATE/TIME INTO DAY AND TIME 



TOP OF STACK CONTAINS DAYS SINCE 17-NOV-1858. CONVERT THIS TO A 
REAL DATE. 



DO OF DATE REQUESTED 

DAY SINCE 17-NOV-1858 IS 

LESS THAN 32 BITS 

ADD THE OFFSET SO WE HAVE THE NUMBER 

OF' DAYS SINCE l-JAN-1501, ALIGNING 

CYCLES SO THAT THE LATER 

TRUNCATIONS AND ROUND-OFFS WORK. 



BIT 


#1,16. (SP) 


BNE 


L0 


MOV 


(SP) ,R3 


MOV 


2(SP) ,R2 



ADD 


#DS15L,R3 


ADC 


R2 


ADD 


#DS15H,R2 



Date Conversion Routine C-3 



MOV 
MOV 
JSR 


#QDAYH,R0 
#QDAYL,R1 
PC,$DIVD 


7 


ASL 
ASL 
MOV 
ASL 
ROL 
ASL 
ROL 
MOV 
MOV 


R3 

R3 

R3,-(SP) 

Rl 

RO 

Rl 

RO 

R1,R3 

R0,R2 


7 
# 

7 
7 

r 
7 

7 


MOV 
MOV 
JSR 

ADD 


#QDAYH,R0 
#QDAYL,R1 
PC,$DIVD 

R3, (SP) 


7 



DIVIDE BY THE NUMBER OF DAYS IN 
A QUADRICENTURY 



R0,R1 = DAYS INTO THIS QUADRICENTURY 
R3 = QUADRICENTURIES SINCE 1501 
CONVERT TO CENTURIES 

AND SAVE 

CONVERT NUMBER OF DAYS INTO 

NUMBER OF QUARTER DAYS 

BY MULTIPLYING BY 4 



DIVIDE BY THE AVERAGE NUMBER OF 
QUARTER DAYS IN A CENTURY 



R0,R1 = QUARTER DAYS INTO CENTURY 
R3 = CENTURIES IN THIS QUAD CENTURY 
ADD TO ACCUMULATED TIME 

BY BASING THE TIME AT 1501, THE CENTURY HAS AN EXTRA LEAP DAY 
INTO THE FIRST CENTURY OF THE QUADRICENTURY. NOW DISCARD ANY 
FRACTION OF A DAY LEFT FROM THE PREVIOUS DIVISION AND ADD IN 3/4 
OF A DAY TO FORCE THE LEAP YEAR INTO THE LAST YEAR OF EACH 4 YEAR 
CYCLE. 



; NOW DIVIDE BY THE AVERAGE NUMBER OF 
; QUARTER DAYS IN A YEAR 



; NUMBER OF DAY IN YEAR 



; COMPUTE # YEARS IN CENTURIES 

; COMPUTE TRUE CALENDAR YEAR 

; SAVE FOR FINAL OUTPUT 

FIND OUT WHETHER THIS YEAR IS A LEAP YEAR. IF NOT, BIAS THE DAY IF 
IT IS PAST FEBRUARY: THE MONTH TABLE IS WRITTEN FOR A LEAP YEAR. 

; INIT LEAP YEAR FLAG TO NO 
; EVERY 400TH IS A LEAP YEAR 

FROM SYSLIB 



BIS 


#3,R1 


MOV 


R1,R3 


MOV 


R0,R2 


MOV 


#0,R0 


MOV 


#FDAYS,R1 


JSR 


PC,$DIVD 


MOV 


R1,R2 


ASR 


R2 


ASR 


R2 


INC 


R2 


MOV 


#100. ,R0 


MOV 


(SP) + ,R1 


JSR 


PC,$MULUS 


ADD 


R3,R1 


ADD 


#1501. ,R1 


MOV 


R1,-(SP) 



MOV 


#1,R4 


MOV 


(SP) ,R0 


MOV 


#400. ,R1 


JSR 


PC,$DIV 


TST 


Rl 


BNE 


LI 
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CLR 


R4 




BR 


L2 


LI: 








MOV 


(SP) ,R0 




MOV 


#100. ,R1 




JSR 


PC,$DIV 




TST 


Rl 




BEQ 


L3 




MOV 


(SP) ,R0 




MOV 


#4,R1 




JSR 


PC,$DIV 




TST 


Rl 




BNE 


L4 




CLR 


R4 


L4: 






L3; 






L2s 







; EVERY 100TH IS NOT 
FROM SYSLIB 

; AND EVERY 4TH IS 
; FROM SYSLIB 



IF THIS IS NOT A LEAP YEAR, 
BIAS THE DAY UP ONE IF IT IS 
PAST FEBRUARY. 



L5: 



CMP R2,#31.+28. 
BLOS L5 
ADD R4,R2 



SCAN THE MONTH TABLE AND FIND OUT WHAT MONTH THIS IS. 



CLR 



Rl 



BO; 



MOVB 


$DAYTB(R1) ,R0 


CMP 


R2,R0 


BLOS 


EO 


SUB 


R0,R2 


INC 


Rl 


CMP 


Rl, #11. 


BLT 


BO 



GET NUMBER OF DAYS IN MONTH 



EO: 



R2 = DAY, Rl = MONTH 

START TO CRANK OUT THE ASCII DATE 



MOV 


R1,-(SP) 






MOV 


R5,R0 


/ 


DAY NUMBER 


MOV 


R2,R1 






MOV 


#0,R2 






JSR 


PC,$CBDMG 






MOVB 


#'-, (R0)+ 


J 


DASH 






} 


INDEX INTO THE MONTH NAME TABLE 


MOV 


(SP) ,R1 






ASL 


Rl 






ADD 


(SP) + ,R1 






ADD 


#$M0NTB,R1 






MOVB 


(RD + 


i 


FILL IN MONTH NAME 


MOVB 


(Rl)+, (R0)+ 






MOVB 


(R1)+,(R0)+ 






MOVB 


#'-, (R0)+ 


i 


DASH 


MOV 


(SP) + ,R1 


i 


ADD YEAR 

Date Conversion Routine 
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MOV 


#0,R2 


JSR 


PC,$CBDMG 


MOVB 


#40, (R0)+ 


MOV 


RQ,R5 



AND A SPACE 

SAVE THE POINTER WHILE WE MESS 

WITH THE TIME OF DAY 



L0: 



NOW CONVERT THE TIME OF DAY TO ASCII 

; DO IF TIME REQUESTED 



L7: 
L6: 



BIT 
BNE 
MOV 
ADD 
MOV 
SUB 
MOV 
MOV 
JSR 
MOV 
MOV 
CMP 
MOV 
MOV 
JSR 
MOV 
MOV 
JSR 
MOV 
MOV 
JSR 

MOV 

JSR 

MOVB 

MOV 

JSR 

MOV 

BIT 

BNE 

MOVB 

JSR 

MOV 

ADD 
MOV 
MOV 
RTS 



*** _ 



C2D 



#2,16. (SP) 

L6 

SP,R1 

#8. ,R1 

SP,R3 

#8. ,SP 

#QNS,R0 

SP,R2 

PC,$DIVQ 

(SP) + ,R3 

(SP) + ,R2 

(SP) + , (SP) + 

#0,R0 

#60. ,R1 

PC,$DIVD 

R1,-(SP) 

#60. ,R1 

PC,$DIVD 

R1,-(SP) 

#24. ,R1 

PC,$DIVD 

R1,R0 
PC,C2D 
#': , (R5)+ 

(SP) + ,R0 
PC,C2D 

(SP) + ,R0 

#10,16. (SP) 

L7 

#':, (R5)+ 

PC,C2D 

R5,R0 

#16. ,SP 
(SP) + ,R2 
(SP) + ,R1 
PC 



POINT TO TIME ON STACK 



ALLOCATE ONE MORE QUAD 
REDUCE TO TIME IN SECONDS 



WHICH IS EXPRESSIBLE IN 32 BITS 

CLEAN GARBAGE FROM STACK 
DIVIDE OUT SECONDS 



AND SAVE THEM 
DIVIDE OUT MINUTES 

AND SAVE 

AND DIVIDE OUT HOURS 

OUTPUT ASCII TIME OF DAY 



GET SECONDS 

IF SECONDS WANTED 



RETURN FINAL STRING POINTER 
FINAL STACK CLEANUP 



CONVERT BINARY TO 2 DECIMAL DIGITS 
THIS ROUTINE IS USED TO OUTPUT THE COMPONENTS OF THE TIME 
INPUTS: 

RO = BINARY VALUE 



C-6 Date Conversion Routine 



wmmm 



OUTPUTS: 



TWO DIGITS STORED AT R5 
R5 BUMPED BY 2 
R0,R1 CLOBBERED 



C2D: 



MOV 


#10. ,R1 


; SPLIT THE DIGITS 


JSR 


PC,$DIV 


; FROM SYS LIB 


ADD 


#'0,R0 


; CONVERT TO ASCII 


ADD 


#'0,R1 




MOVB 


R0, (R5)+ 


; AND STORE 


MOVE 


Rl, (R5) + 




RTS 


PC 





*** - $DIVD DOUBLE PRECISION DIVIDE 

THIS ROUTINE PERFORMS AN UNSIGNED DIVIDE WITH 32 BIT DIVISOR, 
DIVIDEND, QUOTIENT, AND REMAINDER. DIVIDE BY ZERO IS NOT CHECKED. 

ANDREW C. GOLDSTEIN 4 MAR 76 11:41 

BASED ON THE ALGORITHM IN RT-11'S LIBRARY ROUTINE JDIV 

INPUTS: 

R0 = HIGH ORDER DIVISOR 

Rl = LOW ORDER DIVISOR 

R2 = HIGH ORDER DIVIDEND 

R3 = LOW ORDER DIVIDEND 

OUTPUTS: 

R0 = HIGH ORDER REMAINDER 

Rl = LOW ORDER REMAINDER 

R2 = HIGH ORDER QUOTIENT 

R3 = LOW ORDER QUOTIENT 

R4,R5 PRESERVED 



$DIVD: 



10$: 



MOV 


R4,-(SP) 


MOV 


R5,-(SP) 


MOV 


#33., -(SP) 


CLR 


R4 


CLR 


R5 


ROL 


R5 


ROL 


R4 


CMP 


R0,R4 


BHI 


30$ 


BNE 


20$ 


CMP 


R1,R5 



SAVE R4 R5 

SET UP ITERATION COUNT 
QUOTIENT ENDS UP IN R2:R3 
REMAINDER ENDS UP IN R4:R5 
EXPOSE NEW BIT OF NUMERATOR 

DOES DENOM FIT? 

BRANCH IF NOT, C=0 

BRANCH IF YES 

HIGH PARTS SAME, CHECK LOW 
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20$: 



30$: 



BHI 


30$ 




SUB 


R1,R5 




SBC 


R4 




SUB 


R0,R4 




SEC 






ROL 


R3 




ROL 


R2 




DECB 


(SP) 




BGT 


10$ 




TST 


(SP) + 




MOV 


R4,R0 




MOV 


R5,R1 




MOV 


(SP) + , 


R5 


MOV 


(SP) + , 


R4 


RTS 


PC 





BRANCH IF NOT, C=0 

SUBTRACT DENOM FROM REMAINDER 



INDICATE NEW QUOTIENT BIT 
SHIFT IN NEW BIT OF QUOTIENT 

CHECK LOOP COUNT 

BRANCH TO LOOP 

CLEAN THE STACK 

MOVE REMAINDER TO RO Rl 



RESTORE R4 R5 



*** - $DIVQ QUAD DIVIDE ROUTINE 

THIS ROUTINE DOES A 64 BIT UNSIGNED DIVIDE OPERATION. DIVIDE 
BY ZERO IS NOT CHECKED. ALL NUMBERS ARE STORED WITH INCREASING 
SIGNIFICANCE IN INCREASING ADDRESSED BYTES. 

ANDREW C. GOLDSTEIN 17-NOV-76 10:47 

INPUTS: 

RO = ADDRESS OF DIVISOR 

Rl = ADDRESS OF DIVIDEND 

R2 = ADDRESS OF QUOTIENT 

R3 = ADDRESS OF REMAINDER 

OUTPUTS: 

QUOTIENT AND REMAINDER RETURNED IN SPECIFIED ADDRESSES 



$DIVQ: 



10$: 



CALL 


$SAVAL 


MOV 


#65.,-(SP) 


MOV 


R2,R5 


MOV 


(R1)+,(R5)+ 


MOV 


(R1) + ,(R5) + 


MOV 


(R1)+,(R5)+ 


MOV 


(R1)+,(R5)+ 


MOV 


R3,R4 


CLR 


(R4) + 


CLR 


(R4) + 


CLR 


(R4) + 


CLR 


(R4) + 


MOV 


R3 f R4 


ROL 


(R4) + 


ROL 


(R4) + 


ROL 


(R4) + 


ROL 


(R4) + 


MOV 


RO, Rl 


ADD 


#8. ,R1 


MOV 


R4,R5 



SET UP LOOP COUNT 

POINT TO QUOTIENT AREA 

COPY DIVIDEND INTO QUOTIENT AREA 



; COPY REMAINDER POINTER 
; CLEAR OUT REMAINDER AREA 

R4 POINTS TO END OF REMAINDER 
; SHIFT IN NEXT BIT OF DIVIDEND 



POINT TO HIGH ORDER OF DIVISOR 
AND OF REMAINDER AREA 
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CMP -(R1),-(R5) 

BNE 20$ 

CMP -(Rl) ,'-(R5) 

BNE 20$ 

CMP -(R1),-(R5) 

BNE 20$ 

CMP -(R1),-(R5) 

20$: BHI 30$ 

MOV R0,R1 

MOV R3,R4 

SUB (R1)+,(R4)+ 

SBC (R4)+ 

SBC (R4)+ 

SBC (R4) 

CMP -(R4),-(R4) 

SUB (Rl)+, (R4)+ 

SBC (R4) 

SBC 2(R4) 

SUB (R1)+,(R4)+ 

SBC (R4) 

SUB (R1)+,(R4)+ 

SEC 

30$: MOV R2 f R5 

ROL (R5)+ 

ROL (R5) + 

ROL (R5) + 

ROL (R5) + 

DEC (SP) 

BNE 10$ 

TST (SP) + 

RTS PC 



SEE IF DIVISOR IS GREATER THAN 
CURRENT REMAINDER VALUE 



YES: BRANCH, NO SUBTRACT, C IS CLEAR 
POINT TO START OF DIVISOR 
AND START OF REMAINDER 
SUBTRACT DIVISOR FROM REMAINDER 



SET BIT TO SHIFT INTO QUOTIENT 

POINT TO QUOTIENT 

SHIFT NEW BIT IN FROM RIGHT 



C = NEXT BIT OF DIVIDEND 

COUNT ITERATIONS 

AND LOOP 

CLEAN THE STACK 



$MULUS 



10$: 



20$: 



MOV 

CLR 

ROR 

ROR 

BCC 

ADD 

DEC 

BGT 

CMP 

RETURN 

.END 



MOV 

#21, -(SP) 

R0 

R0 

Rl 

20$ 

2(SP) ,R0 

@SP 

10$ 

(SP) + , (SP) + 



R0,-(SP) 
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INDEX 



16-bit signed integer key type, 5-36 

16-bit unsigned binary key type, 5-36 

32-bit signed integer key type, 5-36 

32-bit unsigned binary key type, 5-36 

64-bit date, 5-23 

Abnormal close, unlock file if, 3-29 

Access by RFA, 4-19 

Access fields in user control blocks, 1-2 

Access mode during record operation, 4-19 

Access mode, random, 4-19 

Access mode, sequential, 4-19 

Add blocks to an RMS-11 file, 8-10 

Address, lower, 7-1 

Address, Record's File, 4-19, 4-22, 8-19, 8-23 

and disk files, 8-20, 8-24 
Advantage of different bucket sizes, 5-12 
Allocate user control blocks, 1-2 
Allocation information, 1-13 
Allocation options, 5-10 
Allocation quantity, 5-8 

maximum, 3-4 

minimum, 3-4 

(See also Allocation XAB ALQ field) 

(See also FAB ALQ field) 
Allocation XAB 

AID, 5-3t, 5-4 

ALN, 5-3t, 5-6 

ALQ, 5-3t, 5-8 

ALQ field and current extent, 5-9 

AOP, 5-3t, 5-10 

BKZ, 5-3t, 5-11 

BLN, 5-3t, 5-13 

COD, 5-3t, 5-14 

completely optional, 5-2 

DEQ, 5-3t, 5-15 

DEQ is zero, 3-18 

internal structure of Indexed file, 5-2 

LOC, 5-3t, 5-17 

NXT, 5-3t, 5-19 

placement control, 5-2 

sequencing of, 5-4 

VOL, 5-3t, 5-20 
Allocation, contiguous, 3-28, 5-10 
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Allocation, hard, 5-10 

ALQ. (See File Access Block) 

ANSI magnetic tape, 3-24 

Approximate match, 4-13 

Area, 1-13, 5-2, 5-4. (See also Allocation XAB) 

containing index Level 0, 5-31 

containing index Level 1, 5-48 

containing index Levels 2+, 5-41 

maximum number, 5-4 

maximum number in an Indexed file, 5-74 

minimum number, 5-4 

number in an Indexed file, 5-74 

summary of keys and, in an Indexed file, 5-71 
Area number 

data, 5-31 

index, 5-41 

lowest index level, 5-48 

maximum, 5-31, 5-41, 5-48 
Area, fixed control, 3-32 

maximum, 3-32 

minimum, 3-32 
Argument list 

address of, 1-21 

contents, 1-21 

RMS-11 generates, 1-21 

your program supplies, 1-20 
ASCII, conversion of eight-byte date to, 5-23 
Assemble, 1-2 

command string, 1-22 
Astrophysical base date, Smithsonian, 5-23, 5-26 
Asynchronous record operation, 1-22, 4-25 

outstanding, 8-33 

wait for, 8-33 
Attribute information, 1-2 
Attributes in XAB fields, store file, 8-6 
Attributes of an RMS-11 file, retrieve, 8-12 
Attributes, record, 3-44 
Automatic file extension, 5-15 

failure of, 3-18 

(See also File Access Block DEQ field) 

(See also Allocation XAB DEQ field) 
Available for processing, existing file, 8-12 
Backward, move magnetic tape file forward or, 9-6 
Base date, Smithsonian astrophysical, 5-23, 5-26 
BASIC+, 5-26 

Beginning of a file, logical, 8-29 
BID. (See File Access Block) 
Binary key type 

16-bit unsigned, 5-36 

32-bit unsigned, 5-36 
Bit string data field 

reset bits within a, 7-6 

set bits within a, 7-7 
Bits within a bit string data field 

reset, 7-6 

set, 7-7 
Bits within a field with your value, compares, 7-11 
Bits, least significant, 7-1 
BKS. (See File Access Block) 
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BKT. (See Record Access Block) 

BLN. (See Record Access Block) 

Block boundaries, cross, 3-45 

Block fields, retrieve modify and test, 7-1 

Block header formats, RMS-11 pool, 2-10 

Block I/O, 9-1 

cautions, 9-1 

$READ, 3-23, 9-2t , 9-3 

$READ and ER$E0F error code, 9-4 

$READ and multiple blocks, 9-3 

$READ and unit record terminators, 9-4 

required procedure, 9-1 

$SPACE, 9-2t, 9-6 

virtual block number, 4-4 

$WRITE, 3-24, 9-2t, 9-5 

$WRITE and multiple blocks, 9-5 

$WRITE and partial blocks, 9-5 
Block number 

logical, 3-48, 5-7 

maximum virtual, 4-4 

Root virtual, 5-59 

virtual, 3-48, 5-7, 5-38 
Block size, magnetic tape. (See File Access Block BLS field) 

maximum magnetic tape, 3-10 

minimum magnetic tape, 3-10 

recommended sizes, 3-9 
Block spanning, 3-44 

Block, characters in magnetic tape. (See File Access Block) 
Block, Release Core. (See GSA routine) 
Block, Request Core. (See GSA routine) 
Block, retrieve a specified virtual, 9-3 
Block, user control. (See user control block) 
Block, write a specified virtual, 9-5 
Blocks to an RMS-11 file, add, 8-10 
BLS. (See File Access Block) 
Boundaries, cross block, 3-45 
BPA. (See File Access Block) 
BPT instruction, A-18 
Bucket fill number 

data, 5-34 

index, 5-44 
Bucket size, 4-17, 5-9, 5-11, 5-16, 5-49 

advantage of different, 5-12 

and default extension quantity, 3-17, 5-15 

and initial allocation quantity, 3-4, 5-8 

data, 5-33 

index, 5-43 

maximum, 3-6, 5-11 

minimum, 3-6, 5-11 

valid for Relative and Indexed files only, 3-6 

(See also FAB BKS field) 

(See also Allocation XAB BKZ field) 
Bucket, calculating number of bytes in a, 5-34, 5-44 
Bucket, first data, 5-38 



\m/ 
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Buffer 

allocation, 8-16 

I/O buffer size, 1-6 

record processing use, 1-6 

requirements, 1-7 

RMS-11 control of, 1-6 

user control of, 1-6 
Buffer Descriptor Blocks, 2-lt 

calculating requirements, 2-2 
Buffer pool. (See central buffer pool) 
Buffer pool, private 

address, 3-11 

address on word boundary, 3-11 

and central buffer pool, 3-12 

calculating size of, 3-13 

your program's use of, 3-12 
Buffer size, key, 4-13 
Buffer size, user, 4-34 

and Locate Mode, 4-32 

maximum, 4-34 
Buffer space. (See central buffer pool) 

optimize, 4-25 

release, 8-18 
Buffer 

I/O, 1-6 

private I/O, 1-6. (See also private buffer pool) 

record header, 4-23 

user, 8-23 
Buffers, writes all modified I/O, 8-21 
Bypass RMS-11 record processing, 9-1 

Bytes in a bucket, calculating number of, 5-34, 5-44 
Calculating number of bytes in a bucket, 5-34, 5-44 
Call error, fatal user, A-18 
Calling sequence, 1-20 
Carriage return control, 3-44 
Central buffer pool 

allocated at assembly time, 2-1 

multiple allocation in modules, 2-1 

requirements, 1-2 

Task Builder, 2-1 
Chain of XABs , 5-19, 5-25, 5-55, 5-67, 5-76 
Changability, 5-39 
Change during update, key, 5-39 
Channel, logical, 3-35 

and Record Access Streams, 3-36 

maximum logical, 3-35 

minimum logical, 3-35 

once assigned, 3-36 
Character, null key, 5-53 
Characteristics, key, 5-39 

and Primary Keys, 5-40 

null key, 5-39 

valid combination of, 5-40 
Characters in magnetic tape block. (See File Access Block) 
$CL0SE. (See macro) 
Close 

an open RMS-11 file, 8-2 

rewind magnetic tape file on, 3-29 
unlock file if abnormal, 3-29 



09k 
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Cluster number, device, 5-7 
Clustersize, 3-50 

file extension and, 3-18, 5-16 

maximum, 3-50 

minimum, 3-50 
Code, protection, 5-64 

programmer number, 5-68 

project number, 5-69 
Code, status, 3-54 
Codes, error completion, A-l 
Codes, success completion, A-l 
$C0MPARE. (See macro) 
Compare field with your value, 7-2 
Compares bits within a field with your value, 7-11 
Completion codes, error, A-l 
Completion codes, success, A-l 
Completion routines, 1-19 

register usage during, 1-20 

return control from, 1-20 

RMS-11 operations within, 1-20 
Conditions, inconsistent internal, A-18 
Conditions, severe error, A-2 
$CONNECT. (See macro) 

Contents of a field to your location, copy the, 7-4 
Contents of your location to a field, copy the, 7-9 
Context, 1-22 

Context field, user. (See File Access Block CTX field) 
Context, set, 8-29 

at end-of-file during connect operation, 4-25 
Contiguous allocation, 3-28, 5-10 
Continue processing on the next tape volume, 8-25 
Control block, user. (See user control block) 
Control structures, internal, 1-6 
Control, carriage return, 3-44 
Control, FORTRAN forms, 3-44 
Control, placement, 5-6 

RSTS/E restriction, 5-7 
Conversion of eight-byte date to ASCII, 5-23, 5-26 
Copy the contents of a field to your location, 7-4 
Copy the contents of your location to a field, 7-9 
Core Block, Release. (See GSA routine) 
Core Block, Request. (See GSA routine) 
Crash routine, fatal error, A-2 

and general registers, A-18 

ER$BUG error code, A-19 

ER$FAB error code, A-18 

ER$MAP error code, A-19 

ER$RAB error code, A-18 
$CREATE. (See macro) 
Create 

an RMS-11 file, 8-4 

an RMS-11 task, 1-22 
Creation date and time information, file, 5-21 
Creation date, file, 5-23 

accuracy of, 5-23 
Criterion, match, 4-13 
Cross block boundaries, 3-45 
CTX. (See File Access Block) 
Current extent and Allocation XAB ALQ field, 5-9 
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Current record, 1-22 

Cylinder number, 5-7 

Data area number, 5-31 

Data bucket fill number, 5-34 

Data bucket size, 5-33 ^-^ 

Data bucket, first, 5-38 ~: 

Data field, reset bits within a bit string, 7-6 

Data field, set bits within a bit string, 7-7 

Data type, key, 5-36 

and prologue version number, 5-77 

reassembly requirement, 5-36 
Date and time information 

file creation, 5-21 

file revision, 5-21 
Date-time information, 1-13 

Date to ASCII, conversion of eight-byte, 5-23, 5-26 
Date XAB 

BLN, 5-21t, 5-22 

CDT, 5-21t, 5-23 

COD, 5-21t, 5-24 

NXT, 5-21t, 5-25 

RDT, 5-21t, 5-26 -^ 

RVN, 5-21t, 5-27 ~ 

Date, 64-bit, 5-23, 5-26 
Date, file creation, 5-23 

accuracy of, 5-23 
Date, file revision, 5-26 

accuracy of, 5-26 
Date, Smithsonian astrophysical base, 5-23, 5-26 
Decimal radix, 1-2, 1-10 
Declare RMS-11 facilities, 1-2 
Default extension quantity, 3-17, 5-15 

for file, 3-18 

maximum, 3-18, 5-15 

minimum, 3-17, 5-15 

when Allocation XAB DEQ fields are zero, 3-18 

(See File Access Block DEQ field) 

(See Allocation XAB DEQ field) 
Default name string, 3-20 

and logical names, 3-21 

contents, 3-20 

maximum, 3-22 

notation, 3-21 

size, 3-22 
Defaults, system, 1-16 
Deferred Write, 3-29 
$DELETE. (See macro) 
Delete 

an existing record, 8-17 

an RMS-11 file, 8-8 (See also $ERASE) 

fast, 4-25 

file marked for, 3-29 

records from a Sequential file, 8-30 

temporary file marked for, 3-29 
DEQ. (See File Access Block) 
DEV. (See File Access Block) 

Device characteristics. (See File Access Block DEV field) 
Device cluster number, 5-7 
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Device ID, 1-16 

do not manipulate, 6-2 
used with file ID, 6-2 
Device, unit record, 3-45 

Different bucket sizes, advantage of, 5-12 
Directives, .MCALL, 1-2 

Directory entry(s), remove RMS-11 file's, 8-8 
$DISCONNECT. (See macro) 

Disconnect all Record Access Streams, 8-2 
Disk file size, (See Allocation XAB ALQ field) 
Disk Sequential files and multiblock count, 4-15 
$DISPLAY. (See macro) 
DMA. (See File Access Block) 
Duplicatability, 5-39 
Duplicate key values, 5-39 
Eight-byte date, 5-23, 5-26 

conversion to ASCII, 5-23, 5-26 
End of magnetic tape file, position to, 3-29 
Environment, processing, 1-2 
ER$cod, A-l 

ER$ISI error code after close operation, 8-3 
ER$WER error code on close operation, 8-3 
$ERASE. (See macro) 
Error completion codes, A-l 
Error conditions, severe, A-2 
Error crash routine, fatal, A-2 
and general registers, A-18 
ER$BUG error code, A-19 
ER$FAB error code, A-18 
ER$MAP error code, A-19 
ER$RAB error code, A-18 
Error on relative files, record-exists, 4-26 
Error, fatal user call, A-18 
Establish a Record Access Stream, 8-16 
.EVEN, 1-8, 1-11, 1-13, 1-17 
Exact match, 4-13 
Existing file 

available for processing, 8-12 
supersede, 3-29 
Existing record in an RMS-11 file, replace an, 8-31 
Existing record, delete an, 8-17 
Expanded file name string 
address, 6-3 
length from RMS-11, 6-4 
size from your program, 6-5 
Explanation of locked file, 3-30 
$EXTEND. (See macro) 

Extended Attribute Block, 1-1, 1-13, 5-1 
allocation macros, 1-3 
Allocation XAB, 1-13, 5-2 
and Indexed files, 3-57 
and the FAB, 3-56 
cautions, 1-14 
chain of, 3-56 
Date XAB, 1-13, 5-21 
extension of FAB, 1-13 
field offset macros, 1-3, 5-1 
initialization, 1-14 
initialization macros, 1-3, 5-1 
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Extended Attribute Block (continued) 

Key XAB, 1-13, 5-28 

linking and ordering, 1-14 

ordering by type of XAB, 1-14 

ordering wi thing XAB type, 1-16 ^^k 

Protection XAB, 1-13, 5-64 

required during creation, 1-13 

required during display, 1-13 

Summary XAB, 1-13, 5-71 

XB$ALL, 1-13 

XB$DAT, 1-13 

XB$KEY, 1-13 

XB$PRO, 1-13 

XB$SUM, 1-13 
Extension and clustersize on RSTS/E, file, 3-18, 5-16 
Extension quantity, default. (See default extension quantity) 
Extension, automatic file, 5-15 

failure of, 3-18 
Extent and Allocation XAB ALQ field, current, 5-9 
F$fnm. (See macro) 

FAB. (See Record Access Block) _^ 

FAC. (See File Access Block) -^^. 
Facilities, declare RMS-11, 1-2 

Failure of automatic file extension, 3-18 

Fast delete, 4-25 

Fatal error crash routine, A-2, A-18 

and general registers, A-18 

ER$BUG error code, A-19 

ER$FAB error code, A-18 

ER$MAP error code, A-19 

ER$RAB error code, A-18 
Fatal user call error, A-18, A-18 
FCS, 5-26 

$FETCH. (See macro) 
Field Access Macros 

#0 and $C0MPARE, 7-2 

$C0MPARE, 7-lt, 7-2 

$FETCH, 7-lt, 7-4 

$FETCH and KEY XAB SIZ/POS field, 7-4 

$0FF, 7-lt, 7-6 

$SET, 7-lt, 7-7 

$ST0RE, 7-lt, 7-9 

$STORE and KEY XAB SIZ/POS field, 7-9 

$TESTBITS, 7-lt, 7-11 
Field 

compare with your value, 7-2 

compares bits within to your value, 7-11 

copy the contents of your location to a, 7-9 

copy the contents to your location, 7-4 

key, 5-28 

set bits within a bit string data, 7-7 

reset bits within a bit string data, 7-6 

user context. (See File Access Block CTX field) 
Fields 

access at run time, 1-18 

access macros, 1-18. (See also Field Access Macros) 

in user control blocks, access, 1-2 

modify contents, 1-18, 7-6, 7-7, 7-9 

proper values before operation, 1-8, 1-11, 1-13 
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DEQ vs. XAB DEQ, 3-18 

DEV, l-9t, 3-2t, 3-19 

DNA, l-9t, 1-16, 3-2t 

DNS, 1-16, 3-2t, 3-22 

FAC, l-9t, 3-2t, 3-23 
field offset macros, 1-3, 3-1 

FNA, l-9t, 1-16, 3-2t, 3-25 

l-9t, 1-16, 3-2t, " "" 

3-2t, " "' 
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STV, l-9t, 3-2t, 3-55 
XAB, l-9t, 3-2t, 3-56 
File Address, Record's, 4-19, • 

and disk files, 8-20, 8-24 
File attributes in XAB fields, 
File available for processing, 
File contents unavailable, 8-2 
File creation date, 5-23 



4-22, 8-19, 8-23 

store, 8-6 

ex isting , 8-12 
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accuracy of, 5-23 
File creation date and time information, 5-21 
File default extension quantity, 3-18 
File extension 

and clustersize on RSTS/E, 3-18, 5-16 

automatic, 5-15 

failure of automatic, 3-18 
File forward or backward, move magnetic tape, 9-6 
File ID, 1-16, 3-29 

do not manipulate, 6-6 

used with device ID, 6-6 
File marked for delete, 3-29 
File marked for delete, temporary, 3-29 
File name string 

address, 3-25 

conform to system standards, 3-26 

notation, 3-25 

parsing under RSTS/E, 3-26 

size, 3-27 

use in file specification, 3-25 
File name string size, maximum, 3-27 
File name string, expanded 

address, 6-3 

length from RMS-11, 6-4 

size from your program, 6-5 
File on close, rewind magnetic tape, 3-29 
File on open, rewind magnetic tape, 3-29 
File opened for write operations by RMS-11, 5-27 
File operation, 1-2, 1-19 

calling sequence, 1-20 

FAB associated with the macro, 8-1 

RMS-11 verifies FAB before, 3-5, 3-8 

RMS-11 verifies XAB before, 5-13, 5-14, 5-22, 5-24, 5-29, 5-30, 

5-65, 5-66, 5-72, 5-73 

valid, 3-23 
File Operation Macros, 1-21, 8-1 

$CLOSE, l-22t, 8-lt, 8-2 

$CL0SE and ER$ISI error code, 8-3 

$CL0SE and ER$WER error code, 8-3 

$CL0SE and I/O request, 8-2 

$CL0SE and NAM Block, 8-3 

$CL0SE buffer requirements, 8-2 

$CREATE, l-22t, 8-lt, 8-4 

$CREATE and Allocation XABs, 8-4 

$CREATE and NAM Block, 8-4 

$CREATE buffer requirements, 8-4 

$DISPLAY, l-22t, 8-lt, 8-6 

$DISPLAY buffer requirements, 8-6 

$ERASE, l-22t, 8-lt, 8-8 

$ERASE buffer requirements, 8-8 

$ERASE by file ID, 8-8 

$ERASE while file is open, 8-9 

$EXTEND, l-22t, 8-lt, 8-10 

$EXTEND and Allocation XABs, 8-10 

$EXTEND buffer requirements, 8-10 

$EXTEND restrictions, 8-11 

$OPEN, l-22t, 8-lt, 8-12 

$OPEN and Allocation XABs, 8-12 

$OPEN before $EXTEND, 8-14 

$OPEN buffer requirements, 8-12 

$OPEN by file ID, 8-12 
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File organization, 3-43 

File processing options, 3-28 

File revision date, 5-26 

accuracy of, 5-26 
File revision date and time information, 5-21 
File revision number, 5-27 
File sharing, 1-22, 3-52 

allowing readers, 3-52 

allowing writers, 3-52 

and Sequential files, 3-52 
File size, disk. (See File Access Block ALQ field) 
File specification, 3-25 

full, 1-16, 6-3, 6-4 

maximum full, 6-5 
File, 

add blocks to an RMS-11, 8-10 

close an open RMS-11, 8-2 

create an RMS-11, 8-4 

delete an RMS-11, 8-8. (See also $ERASE) 

delete records from a Sequential, 8-30 

explanation of locked, 3-30 

locate a specified record in a, 8-19 

logical beginning of a, 8-29 

operation related to an entire, 8-1 

position to end of magnetic tape, 3-29 

replace an existing record in an RMS-11, 8-31 

retrieve attributes of an RMS-11, 8-12 

supersede existing, 3-29 

temporary, 3-29 

write a new record into an RMS-11, 8-27 
Files and multiblock count, disk sequential, 4-15 
Files, multivolume magnetic tape, 8-25 
Files, record-exists error on relative, 4-26 
Fill number 

data bucket, 5-34 

honor, 4-26 

index bucket, 5-44 

maximum, 5-34, 5-44 

minimum, 5-34, 5-44 
$FIND. (See macro) 
First data bucket, 5-38 
Fixed control area, 3-32 

maximum, 3-32 

minimum, 3-32 
Fixed-length record format, 3-46 
$FLUSH. (See macro) 
FNA. (See File Access Block) 
FNS. (See File Access Block) 
FOP. (See File Access Block) 
Format 

fixed-length record, 3-46 

record, 3-46 

stream record, 3-46 

undefined record, 3-46 

variable-length record, 3-46 

VFC record, 3-46 
Formats, RMS-11 pool block header, 2-10 
Forms control, FORTRAN, 3-44 
FORTRAN forms control, 3-44 
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Forward or backward, move magnetic tape file, 9-6 

Fragmentation in central buffer pool, 1-6 

FSZ. (See File Access Block) 

Full file specification, 1-16, 6-3, 6-4 

maximum, 6-5 
Generic device characteristics. (See File Access Block DEV field) 
$GET. (See macro) 
Get Space Address (GSA) , 1-7 

Get Space Routine, 2-8. (See also GSA routine) 
$GETGSA. (See macro) 
Global 

labels, 1-10 

symbols, 1-10 
$GNCAL. (See macro) 
Greater-than match, 4-26 
Greater-than-or-equal match, 4-26 
GSA, 1-7. (See also Get Space Address) 
GSA routine 

and general registers, 2-10 

controls all buffer space, 2-8 

expected outputs, 2-8 

failure, 2-12 

interface to, 2-9 

Release Core Block, 2-12 

Request Core Block, 2-12 

retrieving address at run time, 2-9 

$RLCB, 2-12 

RMS-11 inputs to, 2-9 

RMS-11 Pool Block Header Formats, 2-10 

RMS-11 release of space, 2-10 

RMS-11 request for space, 2-10 

RMS-11 trusts, 2-8 

RMS-11 use, 2-8 

$RQCB, 2-12 

serves all files, 2-8 

specifying address at assembly time, 2-8 

specifying address at run time, 2-9 

symmetrical processing, 2-12 

word boundary, 2-8 
GSA$. (See macro) 
Hard allocation, 5-10 
Header buffer, record, 4-23 
Header formats, RMS-11 pool block, 2-10 
Honor fill numbers, 4-26 

Hundreds of nanoseconds since Nov 17, 1858, 5-23, 5-26 
I/O buffer, 1-6 

calculating requirements, 2-7 

private, 1-6. (See also private buffer pool) 

writes all modified, 8-21 
ID, device 

do not manipulate, 6-2 

used with file ID, 6-2 
ID, file 

do not manipulate, 6-6 

used with device ID, 6-6 
IFAB. (See Internal File Access Block) 
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IFI. (See File Access Block) 

Inconsistent internal conditions, A-18, A-19 

Index 

area number, 5-41 

bucket f: ill number, 5-44 

bucket size, 5-43 

level area number, lowest, 5-48 
Index of reference, 4-12 
Indexed file 

maximum number of areas in, 5-74 

maximum number of keys in, 5-75 

number of areas in, 5-74 

number of keys in, 5-75 
$INIT. (See macro) 

Initialize user control blocks, 1-2 
$INITIF. (See macro) 
Integer key type 

16-bit signed, 5-36 

32-bit signed, 5-36 
Internal conditions, inconsistent, A-18 
Internal control structures, 1-6 
Internal File Access Block, 1-8, 2-3, 3-34 
Internal Record Access Block, 1-11, 2-4, 2-5, 4-9 
IRAB. (See Internal Record Access Block) 
ISI. (See Record Access Block) 
KBF. (See Record Access Block) 
Key 

and areas in an Indexed file, summary of, 5-71 

maximum number in an Indexed file, 5-75 

number in an Indexed file, 5-75 
Key buffer size, 4-13 
Key change during update, 5-39 
Key character, null, 5-53 
Key characteristics, 5-39 

and Primary Keys, 5-40 

null, 5-3 9 

valid combination of, 5-40 
Key data type, 5-36 

and prologue version number, 5-77 

reassembly requirement, 5-36 
Key Descriptors, 2-6 
Key field, 5-28 
Key information, 1-13 
Key length, 5-28 
Key name, 5-46 

length, 5-46 
Key of reference, 4-12, 5-58 

maximum, 4-12 

minimum, 4-12 
Key position, 5-28 
Key segments 

maximum number of, 5-52 

minimum number of, 5-52 

multiple, 5-56, 5-61 

number of, 5-52 

position of, 5-56 
Key size, 5-60 

maximum, 5-60 

nonstring, 4-14 

total, 5-63 
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Key type, 5-28 

16-bit signed integer, 5-36 
16-bit unsigned binary, 5-36 
32-bit signed integer, 5-36 
32-bit unsigned binary, 5-36 
string, 5-36 
Key value during random operations, 4-10 
Key value, null, 5-39, 5-53 
Key XAB 

5-28t, 5-29 
5-28t, 5-30 
5-28t, 5-31 
5-28t, 5-33 
5-28t, 5-34 
5-28t, 5-36 
5-28t, 5-38 
5-28t, 5-39 



BLN 
COD 
DAN 
DBS 
DFL 
DTP 
DVB 
FLG 
FLG 
IAN 
IBS 
IFL 
KNM 
LAN 
LVL 
MRL 
NSG 
NUL 
NXT 
POS 
REF 



field contains XB$NUL, 5-53 



5-28t 
5-28t 
5-28t 
5-28t 
5-28t 
5-28t 
5-28t 
5-28t 
5-28t 
5-28t 
5-28t 
5-28t 



5-41 
5-43 
5-44 
5-46 
5-48 
5-50 
5-51 
5-52 
5-53 
5-55 
5-56 
5-58 



required for Indexed file, 5-28 

RVB, 5-28t, 5-59 

SIZ, 5-28t, 5-60 

TKS, 5-28t, 5-63 
Keys 

key characteristic and Primary, 5-40 

maximum number of, 5-58 

random record operations with string, 4-14 

segmented, 5-52, 5-56 

segmented and ascending byte positions, 5-57 

size of segmented, 5-60 
KRF. (See Record Access Block) 
KSZ. (See Record Access Block) 
Label, 1-8, 1-10, 1-11, 1-13, 1-17, 2-8 

global, 1-10 
LCH. (See File Access Block) 
Least significant bits, 7-1 
Length, key, 5-28 
Length, minimum record, 5-51 

and Alternate Keys, 5-51 

and the Primary Key, 5-51 
Level number, root, 5-50 

Locate a specified record in a file, 8-19 
Locked file, explanation of, 3-30 
Logical beginning of a file, 8-29 
Logical block number, 3-48, 5-7 
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Logical channel, 3-35 

and Record Access Streams, 3-36 

maximum, 3-35 

minimum, 3-35 

once assigned, 3-36 
Logical names, 3-21 

Logical unit. (See logical channel) 
Lowest index level area number, 5-48 
Macro 

as arguments in .MCALL directive, 1-3 

buffer pool declaration, 1-3 

$CLOSE, l-8t, 8-2 

$COMPARE, 1-18, 7-2 

$CONNECT, l-10t, 8-16 

$CREATE, 1-8 t, 8-4 

$DELETE, l-10t, 8-17 

$DISCONNECT, l-10t, 8-18 

$DISPLAY, l-8t, 8-6 

$ERASE, l-8t, 8-8 

$EXTEND„ l-8t, 8-10 

F$ALQ, 3-4 

F$BKS, 3-7 

F$BLS, 3-10 

F$BPS, 3-14 

F$CTX, 3-16 

F$DEQ, 3-18 

F$DNA, 3-21 

F$DNS, 3-22 

F$FAC, 3-24 

F$FNA, 3-26 

F$fnm, 1-10 

F$FNS, 3-27 

F$FOP, 3-30 

F$FSZ, 3-32 

F$LCH, 3-35 

F$MRN, 3-38 

F$MRS, 3-40 

F$NAM, 3-42 

F$0RG, 3-43 

F$RAT, 3-4 5 

F$RFM, 3-4 7 

F$RTV, 3-49, 3-51 

F$SHR, 3-53 

F$XAB, 3-56 

FAB$B, 1-3, 1-8 

FAB$E, 1-8 

FB$BLK, 3-44 

FB$CCL, 3-19 

FB$CR, 3-44 

FB$CTG, 3-28 

FB$DEL, 3-23 

FB$DFW, 3-29 

FB$DLK, 3-29 

FB$FID, 3-29 

FB$FIX, 3-46 

FB$FTN, 3-44 

FB$GET, 3-23 

FB$IDX, 3-43 

FB$MDI, 3-19 
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Macro (continued) 
FB$MKD, 3-29 



FB$MKD 
FB$NEF 
FB$POS 
FB$PUT 
FB$REA 
FB$REC 
FB$REL 
FB$RWC 
FB$RWO 
FB$SDI 
FB$SEQ 
FB$SQD 
FB$STM 
FB$SUP 
FB$TMD 
FB$TMP 
FB$TRM 
FB$TRN 
FB$UDF 
FB$UPD 
FB$VAR 
FB$VFC 
FB$WRI 
FB$WRT 



3-29 

3-29 

3-23 

3-23, 

3-19 

3-4 3 

3-29 

3-29 

3-19 

3-4 3 

3-19 

3-46 

3-29 

3-2 9 

3-30 

3-19 

3-23 

3-46 

3-24 

3-46 

3-46 

3-52, 

3-24 
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4-1, 5-1, 6-1 



z lie c 

$FIND, -,-XUL., U-X^ 

$FLUSH, l-10t, 8-2 
$FREE, 8-22 
$GET, l-10t, 8-23 
$GETGSA, 2-9 
$GNCAL, 1-3 
GSA$, 2-8 
$INIT, 1-2, 1-3 
$INITIF, 1-2, 1-3 
N$ESA, 6-3 
N$ESS, 6-5 
N$fnm, 1-17 
NAM$B, 1-3, 1-17 
NAM$E, 1-17 
$NXTV0L, 1-1 Ot, 8- 
$OFF, 1-18, 7-6 
$0PEN, l-8t, 8-12 
ORG$, 1-3 
P$BDB, l-7t, 
P$BUF, l-7t, 
P$FAB, l-7t 
P$IDX, l-7t 
P$RAB, 1-7 t 
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2-lt, 2-2 
2-lt, 2-7 
2-lt, 2-3 
2-lt, 2-6 
2-lt, 2-4 
2-5 



>$RAB, l-7t, 2-lt, 2-4 
>$RABX, l-7t, 2-lt, 2-5 

i>OOL$B, 1-3, l-7t, 2-lt 

P00L$E, l-7t, 2-lt 

processing, 1-1 

$PUT, l-10t, 

R$BKT, 4-4 

R$CTX, 4-6 

R$FAB, 4-7 



- r — 

1-1 
8-27 
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Macro (continued) 
R$KBF, 4-11 
R$KRF, 4-12 
R$KSZ, 4-14 
R$MBC, 4-15 
R$MBF, 4-17 
R$RAC, 4-19 
R$RBF, 4-21 
R$RFA, 4-22 
R$RHB, 4-24 
R$RSZ, 4-29 
R$UBF, 4-33 
R$USZ, 4-34 
RAB$B, 1-3, 1-11 
RAB$E, 1-11 
RB$ASY, 4-25 
RB$EOF, 4-25 
RB$FDL, 4-25 
RB$KEY, 4-19 
RB$KGE f 4-26 
RB$KGT, 4-26 
RB$LOA, 4-26 
RB$MAS, 4-26 
RB$RFA, 4-19 
RB$SEQ, 4-19 
RB$UIF, 4-26 
record operation, 1-22 
$REWIND, l-10t, 8-29 
$SET, 1-18, 7-7 
$SETGSA, 2-9 
$STORE, 1-18, 7-9 
$TESTBITS, 1-18, 7-11 
$TRUNCATE, l-10t, 8-30 
$UPDATE, 1-1 Ot, 8-31 
$WAIT, 8-33 
X$AID, 5-4 
X$ALN, 5-7 
X$ALQ, 5-9 
X$A0P, 5-10 
X$BKZ, 5-11 
X$DAN, 5-3.2 
X$DEQ, 5-16 
X$DFL, 5-35 
X$DTP, 5-37 
X$FLG, 5-40 
X$fnm, 1-14 
X$IAN, 5-42 
X$IFL, 5-45 
X$KNM, 5-47 
X$LAN, 5-49 
X$LOC, 5-18 
X$NUL, 5-53 
X$NXT, 5-19, 
X$POS, 5-57 
X$PRG, 5-68 
X$PRJ, 5-69 
X$PRO, 5-71 
X$REF, 5-58 
X$SIZ, 5-61 



5-25, 5-55, 5-67, 5-76 
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Macro (continued) 

XAB$B, 1-3, 1-13 

XAB$E, 1-13 

XB$ALL, 1-13 

XB$BN2, 5-36 

XB$BN4, 5-36 

XB$CHG, 5-39 

XB$CTG, 5-10 

XB$CYL, 5-7 

XB$DAT, 1-13 

XB$DUP, 5-39 

XB$HRD, 5-10 

XB$IN2, 5-36 

XB$IN4, 5-36 

XB$KEY, 1-13 

XB$LBN, 5-7 

XB$NUL, 5-39 

XB$PRO, 1-13 

XB$STG, 5-36 

XB$SUM, 1-13 

XB$VBN, 5-7 
Macros 

file operation, 1-21 

record operation, 1-22 
Magnetic tape block size 

maximum, 3-10 

minimum, 3-10 

Magnetic tape block, characters in. (See File Access Block BLS field) 
Magnetic tape file 

move forward or backward, 9-6 

multivolume, 8-25 

position to end of, 3-29 

rewind on close, 3-29 

rewind on open, 3-29 
Magnetic tape, ANSI, 3-24 
Marked for delete 

permanent file, 3-29 

temporary file, 3-29 
Mass Insert, 4-26 
Match criterion, 4-13 

approximate, 4-13 

exact, 4-13 

greater-than, 4-26 

greater-than-or-equal , 4-26 
Maximum 

allocation quantity, 3-4 

area number, 5-31, 5-41, 5-48 

bucket size, 3-6, 5-11 

clustersize, 3-50 

default extension quantity, 3-18, 5-15 

default name string, 3-22 

file name string size, 3-27 

fill number, 5-34, 5-44 

fixed control area, 3-32 

full file specification, 6-5 

key of reference, 4-12 

key size, 5-60 

logical channel, 3-35 

magnetic tape block size, 3-10 
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Maximum (continued) 

multiblock count, 4-15 
multibuffer value, 4-17 
number of areas, 5-4 

number of areas in an Indexed file, 5-74 
number of key segments, 5-52 
number of keys, 5-58 

number of keys in an Indexed file, 5-75 
programmer number, 5-68 
project number, 5-69 
Record Number 

Record Number, minimum, 3-37 
Record Size, 3-39, 4-28 

Record Size and fixed-length records, 3-40 
Record Size and Relative files, 3-40 
user buffer size, 4-34 
virtual block number, 4-4 
window size, 3-48 
MBC. (See Record Access Block) 
MBF. (See Record Access Block) 
.MCALL directives, 1-2 
general form, 1-3 

minimizing number of directives, 1-3 
minimum set of arguments, l-3t 
omitting macro names, 1-4 
use across modules, 1-4 
Minimum 

allocation quantity, 3-4 
bucket size, 3-6, 5-11 
clustersize, 3-50 

default extension quantity, 3-17, 5-15 
fill number, 5-34, 5-44 
fixed control area, 3-32 
key of reference, 4-12 
logical channel, 3-35 
magnetic tape block size, 3-10 
Maximum Record Number, 3-37 
number of areas, 5-4 
number of key segments, 5-52 
record length, 5-51 

record length and Alternate Keys, 5-51 
record length and the Primary Key, 5-51 
record size, 3-39 
window size, 3-48 
Mode during record operation, access, 4-19 
Mode 

Random Access, 4-19 
Record Transfer, 4-20 
Sequential Access, 4-19 
Modified I/O buffers, writes all, 8-21 
Module, Root, 1-5 

Move magnetic tape file forward or backward, 9-6 
Moved by record operation, record, 4-20 
MRN. (See File Access Block) 
MRS. (See File Access Block) 
Multiblock count, 4-15 

and I/O buffer size, 4-16 

disk sequential files and, 4-15 

maximum, 4-15 



Index-19 



Multibuffer, 4-17 

and I/O buffer size, 4-18 

and Indexed files, 4-17 

and minimum buffer requirements, 4-18 

and Relative files, 4-17 

maximum value, 4-17 

waste of address space, 4-18 
Multiple key segments, 5-56, 5-61 
Multivolume magnetic tape files, 8-25 
N$fnm. (See macro) 
NAM. (See File Access Block) 
NAM Block, 1-1, 1-16, 6-1 

allocation, 1-17 

allocation macros, 1-3 

and the FAB, 3-41 

cautions, 1-17 

DVI, 1-18, 6-lt, 6-2 

ESA, 1-18, 6-lt, 6-3 

ESA and open/erase by file ID, 6-3 

ESL, 1-18, 6-lt, 6-4 

ESS, 1-18, 6-lt, 6-5 

FID, 1-18, 6-lt, 6-6 

field offset macros, 1-3, 6-1 

indicate existence of, 1-16 

initialization, 1-17 

initialization macros, 1-3, 6-1 
Name Block. (See NAM Block) 
Name string, default, 3-20 

and logical names, 3-21 

contents, 3-20 

maximum size, 3-22 

notation, 3-21 

size, 3-22 
Name string, expanded file 

address, 6-3 

length from RMS-11, 6-4 

size from your program, 6-5 
Name string, file 

address, 3-25 

conform to system standards, 3-26 

maximum size, 3-27 

notation, 3-25 

parsing under RSTS/E, 3-26 

size, 3-27 

use in file specification, 3-25 
Name, key, 5-46 

length, 5-46 
Names, logical, 3-21 

Nanoseconds since Nov 17, 1858, hundreds of, 5-23, 5-26 
New record into an RMS-11 file, write a, 8-27 
Next record, 1-22 

Next tape volume, continue processing on the, 8-25 
Nonstring key size, 4-14 

Nov 17, 1858, hundreds of nanoseconds since, 5-23, 5-26 
Null key character, 5-53 
Null key characteristic, 5-39 
Null key value, 5-39, 5-53 
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Number of 

areas in an Indexed file, 5-74 
bytes in a bucket, calculating, 5-34, 5-44 
key segments, 5-52 
key segments, maximum, 5-52 
key segments, minimum, 5-52 
keys in an Indexed file, 5-75 
keys, maximum, 5-58 
Number 

cylinder, 5-7 
data bucket fill, 5-34 
device cluster, 5-7 
file revision, 5-27 
honor fill, 4-26 
index bucket fill, 5-44 
Logical Block, 3-48, 5-7 
maximum fill, 5-34, 5-44 
maximum programmer, 5-68 
maximum project, 5-69 
Maximum Record 
maximum virtual block, 4-4 
minimum fill, 5-34, 5-44 
minimum Maximum Record, 3-37 
programmer, 5-68 
project, 5-69 
prologue version, 5-77 

prologue version, and key data types, 5-77 
relative record, 4-4, 4-10, 4-13 
relative volume, 5-20 
root level, 5-50 
Root Virtual Block, 5-59 
Virtual Block, 3-48, 5-7, 5-38 
Numeric value, 1-10 
$NXTV0L. (See macro) 
Octal radix, 1-18, 7-1 
$0FF. (See macro) 
$0PEN. (See macro) 

Open, rewind magnetic tape file on, 3-29 
Opened for write operations by RMS-11, file, 5-27 
Operating systems, PDP-11, 1-1 
Operation macros 
file, 1-21 
record, 1-22 
Operation 

access mode during record, 4-19 

asynchronous record, 1-22, 4-25 

calling sequence, 1-20 

file, 1-2, 1-19 

key value during random, 4-10 

optional functions during record, 4-25 

random record, with string keys, 4-14 

record, 1-2, 1-19 

record moved by record, 4-20 

related to an entire file, 8-1 

set proper field values before, 1-19 

suspend program, 8-33 

synchronous record, 1-22 

valid file, 3-23 
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Optimize buffer space, 4-25 

Optional functions during record operations, 4-25 

Options 

allocation, 5-10 

file processing, 3-28 
ORG. (See File Access Block) 
ORG$, 1-3, 1-5. (See also macro) 

CRE, 1-5 

DEL, 1-5 

FIN, 1-5 

for each file organization, 1-5 

general form, 1-5 

GET, 1-5 

IDX, 1-5 

PUT, 1-5 

REL, 1-5 

SEQ, 1-5 

UPD, 1-5 

use, 1-5 
Organization, file, 3-43 

Outstanding asynchronous record operation, 8-33 
Overlays, 1-22 

PDP-11 operating systems, 1-1 
Performance Report, Software, A-19 
Placement control, 5-6 

location, 5-17 

RSTS/E restriction, 5-7 
Pointers, retrieval, 3-48 
Pool block header formats, RMS-11, 2-10 
Pool, central buffer. (See central buffer pool) 
Pool, private buffer (See private buffer pool) 
Position of key segments, 5-56 
Position to end of magnetic tape file, 3-29 
Position, key, 5-28 

Primary Keys, key characteristic and, 5-40 
Printer, 3-45 
Private buffer pool 

address, 3-11 

address on word boundary, 3-11 

and central buffer pool, 3-12 

calculating size of, 3-13 

your program's use of, 3-12 
Private I/O buffer, 1-6. (See also private buffer pool) 
Processing 

bypass RMS-11 record, 9-1 

continue on the next tape volume, 8-25 

environment, 1-2 

existing file available for, 8-12 

options, file, 3-28 
Program operation, suspend, 8-33 
Programmer number, 5-68 

maximum, 5-68 
Project number, 5-69 

maximum, 5-69 
Prologue version number, 5-77 

and key data types, 5-77 
Protection code, 5-64 

programmer number, 5-68 

project number, 5-69 

values, 5-70 
Protection information, 1-13 
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Protection XAB 

BLN, 5-64t, 5-65 

COD, 5-64t, 5-66 

NXT, 5-64t, 5-67 

PRG, 5-64t, 5-68 

PRJ, 5-64t, 5-69 

PRO, 5-64t, 5-70 
$PUT. (See macro) 

Put operation, automatic file extension during, 3-17 
Quantity 

allocation. (See allocation quantity) 

default extension. (See default extension quantity) 

file default extension, 3-18 

maximum allocation, 3-4 

maximum default extension, 3-18, 5-15 

minimum allocation, 3-4 

minimum default extension, 3-17, 5-15 
R$fnm. (See macro) 
RAB. (See Record Access Block) 
RAC. (See Record Access Block) 
Radix 

decimal, 1-2, 1-10 

octal, 1-18, 7-1 
Random Access Mode, 4-19 
Random record operations 

key value during, 4-10 

with string keys, 4-14 
RAT. (See File Access Block) 
RBF. (See Record Access Block) 
Read-sharing, 3-52 
Record Access Block, 1-1, 1-10, 4-1 

allocation, 1-11 

allocation macros, 1-3 

and a FAB, 4-7 

associated with a FAB, 8-16 

ASYN, 1-11 

asynchronous, 4-25 

BID, l-12t, 4-2t, 4-3 

BKT, l-12t, 4-2t, 4-4 

BLN, 1-1 2t, 4-2t, 4-5 

cautions, 1-12 

CTX, l-12t, 4-2t, 4-6 

FAB, l-12t, 4-2t, 4-7 

field offset macros, 1-3, 4-1 

initialization, 1-11 

initialization macros, 1-3, 4-1 

ISI, l-12t, 4-2t, 4-9 

KBF, l-12t, 4-2t, 4-10 

KRF, l-12t, 4-2t, 4-12 

KSZ, l-12t, 4-2t, 4-13 

MBC, l-12t, 4-2t, 4-15 

MBF, l-12t, 4-2t, 4-17 

RAC, l-12t, 4-2t, 4-19 

RB$LOA, 5-34, 5-44 

RBF, l-12t, 4-2t, 4-20 

representing more than one Record, 1-11 

RFA, l-12t, 4-2t, 4-22 

RHB, l-12t, 4-2t, 4-23 
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Record Access Block (continued) 

ROP, l-12t, 4-2t, 4-25 

RSZ, l-12t, 4-2t, 4-28 

STS, l-12t, 4-2t, 4-30 

STV, l-12t, 4-2t, 4-31 

SYN, 1-11 

type, 1-11 

UBF, l-12t, 4-2t, 4-32 

use of RBF/RSZ during processing, 4-21 

USZ, l-12t, 4-2t, 4-34 
Record Access Stream, 1-22 

disconnect all, 8-2 

establish a, 8-16 

terminate a, 8-18 

unlocks a bucket for, 8-22 
Record attributes, 3-44 

Record-exists error on Relative files, 4-26 
Record format, 3-46 

fixed-length, 3-46 

stream, 3-46 

undefined, 3-46 

variable-length, 3-46 

VFC, 3-4 6 
Record header buffer, 4-23 
Record length, minimum, 5-51 

and Alternate Keys, 5-51 

and the Primary Key, 5-51 
Record Management Service, 1-1 
Record Number, Maximum (Relative files only) , 3-37 

minimum, 3-37 
Record number, relative, 4-4, 4-10, 4-13 
Record operation, 1-2, 1-19 

calling sequence, 1-20 

connect, 4-7 

$DELETE, 3-23 

$GET, 3-23 

greater-than match, 4-26 

greater-than-or-equal match, 4-26 

input key, 4-10 

$PUT, 3-23 

relative record number input, 4-4 

RMS-11 verifies RAB before, 4-3, 4-5 

$TRUNCATE, 3-2 3 

$UPDATE, 3-24 
Record Operation Macros, 1-22, 8-15 

$C0NNECT, l-23t, 8-15t, 8-16 

$DELETE, l-23t, 8-15t, 8-17 

$DELETE and Current Record, 8-17 

$DELETE and Sequential file, 8-17 

$DISCONNECT, l-23t, 8-15t, 8-18 

$DISCONNECT and magnetic tape file, 8-18 

$FIND, l-23t, 8-15t, 8-19 

$FIND and duplicate keys, 8-20 

$FIND and ER$RNF error code, 8-20 

$FIND and index of reference, 8-20 

$FLUSH, l-23t, 8-15t, 8-21 

$FREE, l-23t, 8-15t, 8-22 

$FREE and multiple streams, 8-22 

$GET, l-23t, 8-15t, 8-23 

$GET and duplicate keys, 8-24 
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Record Operation Macros (continued) 

$GET and ER$RNF error code, 8-24 

$GET and RAB RBF/RSZ fields, 8-23 

$GET and unit record terminator, 8-24 

$NXTVOL, l-23t, 8-15t, 8-25 

$NXTVOL and input file processing, 8-25 

$NXTVOL and output file processing, 8-25 

$PUT, l-23t, 8-15t, 8-27 

$PUT and Indexed files, 8-28 

$PUT and Next Record, 8-27 

$PUT and Relative files, 8-28 

$PUT and Sequential files, 8-28 

$REWIND, l-23t, 8-15t, 8-29 

$REWIND and RSTS/E magnetic tape, 8-29 

$TRUNCATE, l-23t, 8-15t, 8-30 

$TRUNCATE and Current Record, 8-30 

$TRUNCATE and Next Record, 8-30 

$UPDATE, l-23t, 8-15t, 8-31 

$UPDATE and Current Record, 8-31 

$UPDATE and RAB RBF/RSZ fie, 8-31 

$UPDATE restrictions on Indexed files, 8-32 

$UPDATE restrictions on Relative files, 8-32 

$UPDATE restrictions on Sequential files, 8-32 

$WAIT, l-23t, 8-15t, 8-33 
Record operation 

access mode during, 4-19 

asynchronous, 1-22, 4-25 

optional functions during, 4-25 

random with string keys, 4-14 

record moved by, 4-20 

synchronous, 1-22 
Record processing, bypass RMS-11, 9-1 
Record size, 4-28 

input to put operation, 4-29 

input to update operation, 4-29 
Record size, maximum, 3-39, 4-28 

and fixed-length records, 3-40 

and Relative files, 3-40 
Record size, minimum, 3-39 
Record Transfer Mode, 4-20 

Locate, 4-26 
Record's File Address, 4-19, 4-22, 8-19, 8-23 

and disk files, 8-20, 8-24 
Record 

Current, 1-22 

delete an existing, 8-17 

Next, 1-22 

retrieve a specified, 8-23 

delete from a Sequential file, 8-30 
Reference, key of, 5-58 

maximum, 4-12 

minimum, 4-12 
Relative files, record-exists error on, 4-26 
Relative record number, 4-4, 4-10, 4-13 
Relative volume number, 5-20 
Release buffer space, 8-18 
Release Core Block. (See GSA routine) 
Release of space, RMS-11, 2-10 
Replace an existing record in an RMS-11 file, 8-31 
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Report, Software Performance, A-19 

Request Core Block. (See GSA routine) 

Request for service, 1-2 

Request for space, RMS-11, 2-10 

Reset bits within a bit string data field, 7-6 

Retrieval pointers, 3-48 

Retrieval window size, 3-48 

Retrieve 

a specified record, 8-23 

a specified virtual block, 9-3 

attributes of an RMS-11 file, 8-12 
Revision date and time information, file, 5-21 
Revision date, file, 5-26 

accuracy of, 5-26 
Revision number, file, 5-27 
$REWIND. (See macro) 
Rewind magnetic tape file 

on close, 3-29 

on open, 3-29 
RFA. (See Record Access Block) 
RFA, access by, 4-19 
RFM. (See File Access Block) 
RHB. (See Record Access Block) 
$RLCB. (See GSA routine) 
RMS-11, 1-1 

facilities, declare, 1-2 

Pool Block Header Formats, 2-10 

release of space, 2-10 

request for space, 2-10 
Root level number, 5-50 
Root module, 1-5 
Root Virtual Block Number, 5-59 
ROP. (See Record Access Block) 
Routine, fatal error crash, A-2 

and general registers, A-18 

ER$BUG error code, A-19 

ER$FAB error code, A-18 

ER$MAP error code, A-19 

ER$RAB error code, A-18 
Routines, completion, 1-19 
$RQCB. (See GSA routine) 

RSTS/E, file extension and clustersize on, 3-18, 5-16 
RSZ. (See Record Access Block) 
RTV. (See File Access Block) 
Segmented keys, 5-52, 5-56 

and ascending byte positions, 5-57 

size of, 5-60 

maximum number of segments, 5-52 

minimum number of segments, 5-52 
Segments 

multiple key, 5-56, 5-61 

number of key, 5-52 

position of key, 5-56 
Sequencing of Allocation XABs, 5-4 
Sequential Access Mode, 4-19 
Sequential file 

delete records from a, 8-30 

and multiblock count, 4-15 
Service, request for, 1-2 
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$SET. (See macro) 

Set bits within a bit string data field, 7-7 

Set context, 8-29 

at end-of-file during connect, 4-25 
$SETGSA. (See macro) 
Severe error conditions, A-2 
Sharing, file, 1-22, 3-52 

allowing readers, 3-52 

allowing writers, 3-52 

and Sequential files, 3-52 
SHR. (See File Access Block) 
Signed integer key type 

16-bit, 5-36 

32-bit, 5-36 
Significant bits, least, 7-1 
Size of segmented keys, 5-60 
Size, bucket, 4-17, 5-9, 5-11, 5-16, 5-49 

and default extension quantity, 3-17, 5-15 

and initial allocation quantity, 3-4, 5-8 

valid for Relative and Indexed files only, 3-6 

(See also File Access Block BKS field) 

(See also Allocation XAB BKZ field) 
Si ze 

advantage of different bucket, 5-12 

data bucket, 5-33 

disk file. (See Allocation XAB ALQ field) 

index bucket, 5-43 

key, 5-60 

key buffer, 4-13 

magnetic tape block. (See File Access Block BLS field) 

maximum bucket, 3-6, 5-11 

maximum file name string, 3-27 

maximum key, 5-60 

maximum magnetic tape block, 3-10 

Maximum Record, 3-39, 4-28 

Maximum Record, and fixed-length records, 3-40 

Maximum Record, and Relative files, 3-40 

maximum user buffer, 4-34 

maximum window, 3-48 

minimum bucket, 3-6, 5-11 

minimum magnetic tape block, 3-10 

minimum record, 3-39 

minimum window, 3-48 

nonstring key, 4-14 

recommended for magnetic tape blocks, 3-9 

record, 4-28 

record, input to put operation, 4-29 

record, input to update operation, 4-29 

retrieval window, 3-48 

total key, 5-63 

user buffer, 4-32, 4-34 
Smithsonian Astrophysical Base Date, 5-23, 5-26 
Software Performance Report, A-19 
Space, buffer. (See also central buffer pool) 

optimize, 4-25 

release, 8-18 

RMS-11 release of, 2-10 

RMS-11 request for, 2-JLO 
Spanning, block, 3-44 
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Specification, full file, 1-16, 6-3, 6-4 
Specification, maximum full file, 6-5 
Status code, 3-54, 4-30 
Status value, 3-55, 4-31, A-2 

description of system error codes, A-4 
$ST0RE. (See macro) 

Store file attributes in XAB fields, 8-6 
Stream. (See Record Access Stream) 
Stream record format, 3-46 
String key type, 5-36 

String keys, "random record operations with, 4-14 
String size, maximum file name, 3-27 
Structures, internal control, 1-6 
STS. (See Record Access Block) 
STV. (See Record Access Block) 
STV field, A-2 
SU$cod, A-l 

Success completion codes, A-l 
Summary information, 1-13 

Summary of keys and areas in an Indexed file, 5-71 
Summary XAB 

BLN, 5-71t, 5-72 

COD, 5-71t, 5-73 

NOA, 5-71t, 5-74 

NOK, 5-71t, 5-75 

NXT, 5-71t, 5-76 

PVN, 5-71t, 5-77 
Supersede existing file, 3-29 
Suspend program operation, 8-33 
Symbolic value, 1-10 
Symbols, global, 1-10 
Synchronous record operation, 1-22 
System defaults, 1-16, 3-25 
Systems, PDP-11 operating, 1-1 
Tape block size, magnetic. (See File Access Block BLS field) 

recommended, 3-9 

maximum, 3-10 

minimum, 3-10 
Tape block, characters in magnetic. (See File Access Block) 
Tape file forward or backward, move magnetic, 9-6 
Tape files, multivolume magnetic, 8-25 
Tape volume, continue processing on the next, 8-25 
Task build, 1-2 
Task Builder, 1-5, 1-22 

PSECTS in alphabetical order, 1-23 

/SQ switch, 1-23 
Temporary file, 3-29 

Temporary file marked for delete, 3-29 
Terminal, 3-45 

Terminate a Record Access Stream, 8-18 
$TESTBITS. (See macro) 
Time information 

file creation date and, 5-21 

file revision date and, 5-21 
Total key size, 5-63 
Transfer mode, record, 4-20 
$TRUNCATE. (See macro) 
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Type, key, 5-28 

16-bit signed integer key, 5-36 

16-bit unsigned binary key, 5-36 

32-bit signed integer key, 5-36 

32-bit unsigned binary key, 5-36 
' it % / and prologue version number, 5-77 

key data, 5-36 

reassembly requirement, 5-36 

string key, 5-36 
UBF. (See Record Access Block) 
Undefined record format, 3-46 
Unit record device, 3-45 
Unit, logical. (See logical channel) 
Unlock file if abnormal close, 3-29 
Unlocks a bucket for a Record Access Stream, 8-22 
Unsigned binary key type 

16-bit, 5-36 

32-bit, 5-36 
$UPDATE. (See macro) 
Update operation 

automatic file extension during, 3-17 

key change during, 5-39 
W' User buffer, 8-23 

User buffer size, 4-34 

and Locate Mode, 4-32 
- maximum,, 4-34 
User call error, fatal, A-18 

User context field. (See Record Access Block CTX field) 
User control block 

access fields in, 1-2 

allocate, 1-2 
} allocation at assembly time, 1-8 

'*'—* assembly-time field initialization, 1-8 

data fields in, 1-8 

initialize, 1-2 

other than default value in field, 1-10 

run-time field access, 1-8 
(See also File Access Block) 
(See also Record Access Block) 
(See also Extended Attribute Block) 
(See also NAM Block) 
- USZ. (See Record Access Block) 

^"^ Variable-length record format, 3-46 

Variable-with-fixed-control. (See VFC) 
Version number, prologue, 5-77 

and key data types, 5-77 
VFC 

and no record header buffer, 4-23 

and scatter- read, gather-write, 4-23 

during Locate Mode, 4-24 

record format, 3-46 

records, 3-32, 4-23 
Virtual block number, 3-48, 5-7, 5-38 

maximum, 4-4 

Root, 5-59 
Virtual block 

retrieve a specified, 9-3 

write a specified, 9-5 
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Volume number, relative, 5-20 

Volume, continue processing on the next 

Wait for asynchronous record operation, 

Window size 
maximum, 3-48 
minimum, 3-48 
retrieval, 3-48 

Write 

a new record into an RMS-11 file, 8-27 
a specified virtual block, 9-5 
operations by RMS-11, file opened 

Write-sharing, 3-52 

Writes all modified I/O buffers, 8-21 

X$fnm. (See macro) 

XAB. (See File Access Block) 



tape , 
8-33 



8-25 



for, 5-2 7 
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